OpenCode

오픈소스 터미널 코딩 에이전트 OpenCode에 PleumRouter를 커스텀 공급자로 추가합니다.

OpenCode는 터미널(TUI)에서 쓰는 오픈소스 코딩 에이전트로, OpenAI 호환 엔드포인트를 커스텀 공급자로 추가할 수 있습니다. PleumRouter는 OpenAI Chat Completions(/v1/chat/completions) 형식으로 연결됩니다.

빠른 시작#

1
OpenCode 설치
이미 설치했다면 건너뛰세요.
install.sh
macOS·Linux.
```
curl -fsSL https://opencode.ai/install | bash
opencode --version
```
패키지 이름은 `opencode-ai`입니다.
```
npm install -g opencode-ai
opencode --version
```
API 키 발급
대시보드의 API 키 페이지에서 plm_로 시작하는 키를 만들어 복사하세요. 처음에는 일·주·월 예산을 함께 걸어 두는 것을 권장합니다.

PleumRouter로 연결

세 가지 중 하나만 고르세요. OpenCode는 커스텀 엔드포인트를 환경변수가 아니라 opencode.json의 provider 블록으로만 읽습니다.

pleum launch

내 `opencode.json`은 건드리지 않고 이번 실행에만 provider 설정을 씁니다. 다만 OpenCode의 모델 즐겨찾기(`model.json`)에는 PleumRouter 모델이 추가되어 남습니다.

npm i -g pleumrouter
pleum login              # sign in with the browser
pleum launch opencode    # temporary provider config for this run only

먼저 셸에서 발급한 키를 `PLEUM_API_KEY` 환경변수로 `export`하세요. 키는 `{env:PLEUM_API_KEY}`로 읽습니다.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "pleum/gpt-6-sol",
  "provider": {
    "pleum": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "PleumRouter",
      "options": {
        "baseURL": "https://apirouter.pleum.ai/v1",
        "apiKey": "{env:PLEUM_API_KEY}"
      },
      "models": {
        "gpt-6-sol": {},
        "claude-sonnet-5": {},
        "deepseek-ai/DeepSeek-V4.1-Flash": {}
      }
    }
  }
}

`/connect`는 키만 저장합니다. 주소와 모델은 `opencode.json`에 적어야 합니다.

# 1) in OpenCode: run /connect, choose Other, enter provider id "pleum", paste your plm_ key
#    (stored in ~/.local/share/opencode/auth.json)
#
# 2) opencode.json — same block as above, but without "apiKey":
#    provider.pleum.options = { "baseURL": "https://apirouter.pleum.ai/v1" }

4
모델을 고르고 확인
opencode를 실행하고 /models에서 PleumRouter 모델을 고르세요. opencode.json의 최상위 model에 pleum/<모델 ID>를 적어 두면 그 모델로 시작합니다. 프롬프트 한 번에 응답이 오면 연결 성공입니다.
Terminal
```
cd your-project
opencode

# inside OpenCode, pick a PleumRouter model
/models
```

OpenCode에서 PleumRouter를 쓰는 이유#

선불 크레딧으로 사용한 만큼만 결제합니다. 도구 제작사의 구독과 별개로 크레딧이 차감됩니다.
키마다 예산과 한도를 겁니다. API 키별 일·주·월 예산과 모델 허용 목록, 팀 예산으로 에이전트의 비용을 관리합니다.
한 키로 여러 모델을 씁니다. Claude·GPT·Gemini·오픈 모델을 골라 쓰고, 공급자 장애 시 자동 재시도·폴백이 동작하며, 사용량은 대시보드에서 봅니다.

작동 방식#

OpenCode는 @ai-sdk/openai-compatible 어댑터로 {baseURL}/chat/completions에 OpenAI Chat Completions 요청을 보냅니다. PleumRouter는 이 요청을 받아 스트리밍(SSE)과 도구 호출을 그대로 처리해 선택한 모델의 공급자로 전달합니다. 인증은 plm_ 키를 Authorization: Bearer로 보냅니다. provider.pleum의 pleum은 공급자 ID이고, 모델은 pleum/<모델 ID> 형식으로 가리킵니다.

설정 레퍼런스#

항목	설명
modelpleum/gpt-6-sol	선택. 시작할 때 쓸 기본 모델(`공급자 ID/모델 ID`).
provider.pleum.npm@ai-sdk/openai-compatible	OpenAI 호환 Chat Completions 어댑터.
provider.pleum.namePleumRouter	모델 선택 화면에 표시되는 이름.
options.baseURLhttps://apirouter.pleum.ai/v1	`/v1`까지입니다. 끝에 `/chat/completions`를 붙이지 마세요.
options.apiKey{env:PLEUM_API_KEY}	환경변수에서 키를 읽습니다. `/connect`로 저장했다면 생략합니다.
models{ "gpt-6-sol": {} }	`/models`에 보이게 할 모델 ID 목록. 여기에 적은 것만 나타납니다.
models.<id>.limit{ "context": 1050000, "output": 128000 }	선택. 컨텍스트·출력 한도. 적으면 대화 압축 시점이 정확해집니다.
설정 파일 위치./opencode.json	프로젝트 단위. 사용자 전체에는 `~/.config/opencode/opencode.json`을 씁니다.
키 저장 위치~/.local/share/opencode/auth.json	`/connect`로 넣은 키가 저장되는 파일.

모델 선택#

models에 적은 ID만 /models에 나타납니다. 정확한 ID는 모델 카탈로그나 GET /v1/models에서 확인하세요. 모델마다 limit.context·limit.output을 적어 두면 OpenCode가 대화 압축 시점을 정확히 잡고, name은 선택 화면에 보일 이름입니다. claude-sonnet-latest처럼 -latest를 붙이면 그 계열의 최신 릴리스로 연결됩니다. 시작할 때마다 모델을 고르기 싫다면 최상위 model에 pleum/<모델 ID>를 넣으세요. 터미널·데스크톱 앱·opencode run에 모두 적용됩니다. OpenCode 2는 opencode --model을 받지 않으므로 시작 모델은 이 설정으로 정하고, opencode run은 --model pleum/<모델 ID>로 모델을 지정할 수 있습니다.

opencode.json

{
  "provider": {
    "pleum": {
      "models": {
        "gpt-6-sol": {
          "name": "GPT-6 Sol",
          "limit": { "context": 1050000, "output": 128000 }
        },
        "claude-sonnet-latest": { "name": "Claude Sonnet (latest)" }
      }
    }
  }
}

OpenCode는 여러 공급자를 쓰도록 만든 도구입니다. 도구 호출 품질은 모델마다 다를 수 있습니다.

지원 범위#

기능	상태	설명
스트리밍(SSE)	지원	Chat Completions 스트리밍을 그대로 사용합니다.
도구 호출	지원	OpenAI 형식 `tools`를 통과시킵니다. 모델이 도구 호출을 지원해야 합니다.
이미지 입력	지원	선택한 모델이 이미지 입력을 지원할 때만 동작합니다.
모델 목록 자동 조회	일부	OpenCode가 커스텀 공급자의 목록을 불러오지 않으므로 `models`에 직접 적어야 합니다.

데스크톱 앱·IDE 확장#

OpenCode 데스크톱 앱과 IDE 확장은 터미널과 같은 opencode.json과 auth.json을 읽습니다. 터미널에서 한 번 연결했다면 따로 설정할 필요 없이 모델만 고르면 됩니다. 설정 파일을 바꾼 뒤에는 앱을 완전히 종료했다가 다시 여세요. 공급자 목록은 시작할 때만 읽습니다.

문제 해결#

증상	원인과 조치
401 Unauthorized	`{env:PLEUM_API_KEY}`가 비어 있거나 키가 틀렸습니다. 같은 셸에서 `echo $PLEUM_API_KEY`로 확인하고, `/connect`로 저장했다면 `auth.json`의 키가 맞는지 보세요.
키를 저장했는지 모르겠습니다	`opencode auth list`로 저장된 자격 증명을 확인하세요. `pleum`이 목록에 없으면 `/connect`를 다시 실행합니다.
모델을 추가했는데 목록에 없습니다	OpenCode(데스크톱 앱 포함)를 완전히 종료했다가 다시 여세요. 공급자와 모델 목록은 시작할 때만 읽습니다.
`/models`에 PleumRouter 모델이 안 보입니다	`opencode.json`의 `models`에 ID를 적었는지, 공급자 ID(`pleum`)가 `/connect`에 입력한 것과 같은지 확인한 뒤 OpenCode를 다시 시작하세요.
`/connect`만 했는데 동작하지 않습니다	`/connect`는 키만 저장합니다. `provider.pleum.options.baseURL`과 `models`는 `opencode.json`에 적어야 합니다.
404 Not Found	`baseURL`이 `https://apirouter.pleum.ai/v1`인지 확인하세요. 끝에 `/chat/completions`를 붙이면 안 됩니다.
model not found	`models`에 적은 ID가 카탈로그에 없습니다. `GET /v1/models`로 정확한 ID를 확인하세요.
설정 파일을 어디에 둬야 할지 모르겠습니다	이 프로젝트에서만 쓰려면 프로젝트 루트의 `./opencode.json`, 모든 프로젝트에서 쓰려면 `~/.config/opencode/opencode.json`입니다.

비용·보안 팁#

키에 예산을 걸어 두세요. 코딩 에이전트는 한 작업에서 모델을 여러 번 호출하고 긴 컨텍스트를 반복해 보냅니다. API 키에 일·주·월 예산을 설정하면 비용을 예측하기 쉽습니다.
키는 git에 올리지 마세요. 셸 프로필이나 설정 파일에 넣은 키가 저장소에 커밋되지 않게 하고, 유출이 의심되면 대시보드에서 바로 폐기한 뒤 새로 발급하세요.
민감한 코드라면 처리 위치를 확인하세요. 프롬프트와 코드는 고른 모델의 공급자에게 전달됩니다. 데이터 처리 위치와 개인정보 마스킹으로 범위를 정할 수 있습니다.