---
title: "opencode 커스텀 OpenAI 호환 제공자 설정 | BroadRouter"
description: "opencode.jsonc에서 BroadNet Inference를 opencode 코딩 에이전트의 커스텀 OpenAI 호환 제공자로 추가하고, 모델 별칭과 capabilities, limit을 설정합니다."
url: https://broadrouter.com/ko/guides/opencode-custom-provider/
lang: ko
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

이 페이지는 영어 원문을 AI의 도움을 받아 번역했습니다. [영어 원문 읽기](https://broadrouter.com/guides/opencode-custom-provider/) (2026-11-16 업데이트).

# opencode에 BroadNet Inference를 커스텀 제공자로 추가하기

업데이트 2026-11-16

opencode.jsonc의 providers 아래에 broadnet 항목을 추가하고 package는 @opencode/ai/providers/openai-compatible, settings.baseURL은 https://inference.broadnet.ai/v1, env는 BROADNET\_API\_KEY로 지정하세요. 짧은 모델 키를 modelID로 broadnet/glm-5.3 같은 BroadNet ID에 연결한 뒤 /models에서 모델을 고릅니다. npm @ai-sdk/openai-compatible과 options.baseURL을 쓰는 예전 V1 설정도 계속 작동합니다.

opencode는 터미널용 오픈 소스 코딩 에이전트입니다. 기본 카탈로그에 없는 제공자는 `opencode.jsonc`에 **커스텀 제공자**로 추가합니다. BroadNet Inference는 OpenAI chat completions 형식을 따르므로 opencode의 OpenAI 호환 런타임 패키지를 씁니다. 이 가이드는 현재(V2) opencode 문서를 따릅니다.

## 설정

1.  opencode를 실행할 셸에서 **키를 export하세요.**

```bash
export BROADNET_API_KEY='your-broadnet-key'
```

2.  **설정 파일을 만드세요.** 프로젝트에 `opencode.jsonc`로 두거나, 모든 곳에서 쓰려면 `~/.config/opencode/opencode.jsonc`에 두세요.

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "model": "broadnet/glm-5.3",
  "providers": {
    "broadnet": {
      "name": "BroadNet Inference",
      "env": ["BROADNET_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://inference.broadnet.ai/v1"
      },
      "models": {
        "glm-5.3": {
          "modelID": "broadnet/glm-5.3",
          "name": "GLM 5.3",
          "capabilities": { "tools": true, "input": ["text"], "output": ["text"] },
          "limit": { "context": 1048576, "output": 16000 }
        },
        "deepseek-v4.1-flash": {
          "modelID": "broadnet/deepseek-v4.1-flash",
          "name": "DeepSeek V4.1 Flash",
          // BroadNet's docs don't list tool calling for this model: test it first
          "capabilities": { "tools": true, "input": ["text", "image"], "output": ["text"] },
          "limit": { "context": 1048576, "output": 16000 }
        },
        "qwen3.8-27b": {
          "modelID": "broadnet/qwen3.8-27b",
          "name": "Qwen3.8 27B",
          "capabilities": { "tools": true, "input": ["text", "image"], "output": ["text"] },
          "limit": { "context": 262144, "output": 16000 }
        }
      }
    }
  }
}
```

3.  **opencode를 실행하고** `/models`로 **모델을 고르세요.** 참조 형식은 `broadnet/<맵 키>`이며, 예를 들면 `broadnet/glm-5.3`입니다. opencode는 `modelID` 값을 BroadNet에 보냅니다.

설정 파일은 병합됩니다. opencode는 전역 파일을 먼저 적용하고, 그다음 현재 디렉터리에서 위쪽으로 찾은 프로젝트 파일(가장 먼 것부터), 마지막으로 `.opencode/` 설정을 적용합니다. 따라서 프로젝트 파일이 전역 제공자 설정을 덮어쓸 수 있습니다. 회사에서 관리형 시스템 설정을 쓴다면 그 설정이 둘 다보다 우선합니다. 키는 파일이 아니라 환경 변수에 두세요. 그래야 설정 파일을 버전 관리에 넣을 수 있습니다.

## 별칭을 쓰는 이유

BroadNet ID에는 이미 슬래시가 들어 있습니다(`broadnet/glm-5.3`). `models` 맵의 키는 opencode가 표시하고 선택하는 값이고, `modelID`는 실제로 전송하는 값입니다. 짧은 키를 쓰면 참조를 읽기 쉽습니다.

`capabilities`와 `limit`은 직접 설정하세요. 카탈로그에 없는 모델에 대해 opencode는 JSON 도구 지원, 텍스트와 이미지 입력, 200,000토큰 컨텍스트, 출력 32,000토큰을 가정합니다. opencode 문서는 이를 감지한 값이 아니라 대체(fallback) 가정이라고 설명합니다. 위의 `output` 값 16000은 BroadNet의 한도가 아니라 저희가 제안하는 값이며, 추론할 여유를 남겨 둡니다.

### 예전 V1 설정

opencode V2는 V1 형식도 계속 읽으므로, 다음과 같은 기존 블록은 그대로 작동합니다.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "broadnet": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "BroadNet Inference",
      "options": {
        "baseURL": "https://inference.broadnet.ai/v1",
        "apiKey": "{env:BROADNET_API_KEY}"
      },
      "models": {
        "broadnet/glm-5.3": { "name": "GLM 5.3" }
      }
    }
  }
}
```

네이티브 V2 형식에서는 `provider`가 `providers`로, `npm`이 `package`로 바뀌고(AI SDK 패키지를 계속 쓰려면 `aisdk:@ai-sdk/openai-compatible`), `options.baseURL`과 `options.apiKey`는 `settings` 아래로 옮겨집니다. 필드별 대응은 [opencode V1 마이그레이션 가이드](https://opencode.ai/docs/migrate-v1/)에 정리되어 있습니다.

## 어떤 모델을 고를까

| 작업 | 모델 | 비고 |
| --- | --- | --- |
| 도구를 쓰는 에이전트 코딩 | [GLM 5.3](https://broadrouter.com/ko/models/glm-5.3/) | 도구와 구조화된 출력 표기, 1M 컨텍스트 |
| 스크린샷, 아랍어 | [Qwen3.8 27B](https://broadrouter.com/ko/models/qwen3.8-27b/) | 도구와 이미지, 262K 컨텍스트 |
| 종일 쓰는 세션, 정액 요금 | [DeepSeek V4.1 Flash](https://broadrouter.com/ko/models/deepseek-v4.1-flash/) | 무제한 플랜, BroadNet이 도구 지원을 표기하지 않음 |

opencode는 도구 호출에 의존합니다. BroadNet 문서에는 DeepSeek V4.1 Flash의 도구 호출 지원이 나오지 않으므로, 위 설정에서는 이를 테스트가 필요한 가정으로 표시했습니다. Full Moon 한 달($60)을 구매하기 전에 Meteor 1시간($1)으로 실제 작업을 돌려 보세요.

## 문제 해결

-   **401.** `BROADNET_API_KEY`의 키가 틀렸거나, 만료되었거나, 종량제 사용 가능 금액이 소진되었습니다. opencode를 실행하는 프로세스에 이 변수가 설정되어 있는지 확인하세요.
-   **모델을 찾을 수 없거나 거부됨.** 맵 키(`broadnet/glm-5.3`)를 선택하고, `modelID`가 BroadNet의 ID와 정확히 같은지 확인하세요. 참조는 대소문자를 구분합니다. 유료 모델은 충전이 필요하며, 초기 크레딧($5 상당)은 `broadnet/gemma-4-26b-a4b` 모델과 Transcribe 모델 두 개에만 쓸 수 있습니다.
-   **빈 답변.** `limit.output`을 늘리세요. [답변이 비어서 오는 이유](https://broadrouter.com/ko/guides/reasoning-tokens-empty-response/)를 참고하세요.
-   **429.** 종량제 키는 분당 30 요청, 동시 처리 4 건까지 허용합니다. 재시도도 포함됩니다. [오류와 재시도](https://broadrouter.com/ko/guides/errors-and-retries/)를 참고하세요.
-   **플랜에서 서브에이전트를 쓸 때.** [플랜 세션](https://broadrouter.com/ko/guides/unlimited-llm-api-sessions/)은 각각 한 번에 요청 하나를 처리하므로, 서브에이전트마다 세션이 따로 없으면 병렬 서브에이전트는 대기열에 쌓입니다.

## 이 가이드의 용어

[종량제(Pay-as-you-go)](https://broadrouter.com/ko/glossary/pay-as-you-go/)

종량제(pay-as-you-go)는 구독이나 최소 약정 없이 토큰, 요청, 오디오 분 같은 단위로 사용량을 측정해 쓴 만큼만 내는 요금 방식입니다. 대부분의 LLM API가 선불 잔액에서 차감하거나 정기 청구서를 발행하는 식으로 이렇게 과금합니다.

[구조화된 출력(Structured output)](https://broadrouter.com/ko/glossary/structured-output/)

구조화된 출력(structured output)은 모델의 응답을 개발자가 지정한 형식, 주로 JSON Schema에 맞추도록 제한해 코드가 안정적으로 파싱할 수 있게 하는 LLM API 기능입니다. 유효한 JSON만 보장하고 특정 구조는 보장하지 않는 JSON 모드보다 더 엄격합니다.

[동시 처리(concurrency)](https://broadrouter.com/ko/glossary/concurrency/)

동시 처리(concurrency)는 클라이언트가 같은 시점에 진행 중인 요청 수입니다. LLM API는 분당 요청 수와 별도로 키나 플랜마다 이를 제한하는 경우가 많습니다. 열려 있는 요청은 응답이 끝날 때까지 GPU 용량을 차지하기 때문입니다.

[속도 제한(rate limit)](https://broadrouter.com/ko/glossary/rate-limit/)

속도 제한(rate limit)은 API가 일정 시간 동안 클라이언트가 사용할 수 있는 양에 두는 상한으로, 분당 요청 수나 분당 토큰 수 같은 기준이 있습니다. 한도를 넘은 요청은 사용량이 다시 한도 아래로 내려갈 때까지 거부되며, 보통 HTTP 429 Too Many Requests가 반환됩니다.

[AI 에이전트(AI agent)](https://broadrouter.com/ko/glossary/agent/)

AI 에이전트는 언어 모델이 목표를 향해 스스로 단계를 정하는 시스템입니다. 어떤 도구를 호출할지 결정하고, 결과를 읽고, 최종 답변을 내거나 한도에 닿을 때까지 이를 반복합니다. 정해진 지점에서 모델을 호출하는 고정된 스크립트는 보통 워크플로라고 부릅니다.

[Chat Completions API](https://broadrouter.com/ko/glossary/chat-completions-api/)

Chat Completions API는 OpenAI의 HTTP 엔드포인트인 POST /v1/chat/completions로, 모델 이름과 역할이 붙은 메시지 목록을 받아 모델의 다음 메시지를 반환합니다. 이 요청과 응답 구조는 OpenAI 호환 제공업체와 SDK가 재사용하는 공통 형식이 되었습니다.

[OpenAI 호환 API(OpenAI-compatible API)](https://broadrouter.com/ko/glossary/openai-compatible-api/)

OpenAI 호환 API는 POST /v1/chat/completions처럼 OpenAI API와 같은 요청 및 응답 형식을 받는 HTTP API입니다. 그래서 OpenAI SDK와 도구는 base URL, API 키, 모델 이름만 바꾸면 이 API를 그대로 사용할 수 있습니다.

## 자주 묻는 질문

### opencode가 BroadNet 모델을 찾지 못하는 이유는 무엇인가요?

opencode는 모델 참조를 "제공자/맵 키"로 해석하며, ID는 대소문자를 구분합니다. 아래 설정에서는 broadnet/glm-5.3을 선택하세요. 여기서 glm-5.3이 맵 키입니다. modelID 값은 BroadNet에 전송되는 값일 뿐입니다.

### 제 설정은 provider와 npm에 @ai-sdk/openai-compatible을 씁니다. 잘못된 건가요?

아닙니다. 그것은 V1 형식이며, opencode 마이그레이션 가이드는 계속 지원된다고 밝힙니다. 네이티브 V2 형식에서는 provider가 providers로, npm이 package(aisdk:@ai-sdk/openai-compatible)로, options.baseURL이 settings.baseURL로 바뀝니다.

### opencode 응답이 비어 있는 이유는 무엇인가요?

모델이 출력 예산을 추론에 다 썼기 때문입니다. 해당 모델의 limit.output을 늘리세요. BroadNet에서는 추론도 max\_tokens에 포함됩니다.

## 관련 가이드

-   [BroadNet Inference에서 Cline 사용하기(OpenAI Compatible 제공자)](https://broadrouter.com/ko/guides/cline-openai-compatible/)
-   [에이전트용 무제한 LLM API 플랜은 어떻게 작동하나요?](https://broadrouter.com/ko/guides/unlimited-llm-api-sessions/)
-   [추론 모델이 빈 답변을 반환하는 이유](https://broadrouter.com/ko/guides/reasoning-tokens-empty-response/)
-   [BroadNet Inference에서 Vercel AI SDK 사용하기](https://broadrouter.com/ko/guides/vercel-ai-sdk-openai-compatible/)
-   [BroadNet Inference와 함께 쓸 수 있는 모든 도구 (영어)](https://broadrouter.com/integrations/): SDK, 코딩 에이전트, 채팅 UI, 자동화 도구와 각 도구의 정확한 설정

실제 워크로드로 테스트해 보세요. 신규 계정에는 US$5 상당의 초기 크레딧이 제공되며 Gemma 및 음성 전사에 사용할 수 있습니다. DeepSeek, GLM 및 Qwen3.8 모델은 충전이 필요합니다.

[시작하기](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-guides-opencode-custom-provider&utm_content=page-cta) ·

**출처**

-   [opencode 문서, Providers(커스텀 제공자)(2026-11-14 확인)](https://opencode.ai/docs/providers/)
-   [opencode 문서, Models(별칭, capabilities, limit)(2026-11-14 확인)](https://opencode.ai/docs/models/)
-   [opencode 문서, 설정 파일 위치(2026-11-14 확인)](https://opencode.ai/docs/config/)
-   [opencode 문서, V1에서 마이그레이션(2026-11-14 확인)](https://opencode.ai/docs/migrate-v1/)
-   [BroadNet Inference API 레퍼런스 (영어)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-guides-opencode-custom-provider&utm_content=sources)
