본문으로 건너뛰기

opencode 연동

opencode에 Letsur provider와 사용할 모델을 등록하세요.

provider 설정과 수동 모델 등록, 환경변수 키 전달을 다룹니다.

시작 전 준비

opencode는 OpenAI 호환 endpoint를 provider로 직접 등록합니다. 게이트웨이를 provider 하나로 추가하고, 사용할 모델을 그 아래에 나열합니다.

  • AI 게이트웨이 API 키

    현재 사용할 수 있는 AI 게이트웨이 API 키를 준비합니다.

  • 모델 코드

    에셋에 표시된 정확한 코드를 확인합니다.

  • opencode CLI

    전역 또는 프로젝트 환경에서 실행할 opencode CLI를 설치합니다.

npm i -g opencode-ai

공통 base URL과 키 형식은 외부 도구 연동에서 비교합니다.

연결 설정

provider 등록

전역 설정은 ~/.config/opencode/opencode.json, 프로젝트별 설정은 프로젝트 루트의 opencode.json에 작성합니다.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "letsur": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Letsur Gateway",
      "options": {
        "baseURL": "https://gw.letsur.ai/v1",
        "apiKey": "{env:LETSUR_API_KEY}"
      },
      "models": {
        "<MODEL_CODE>": { "name": "Letsur model" }
      }
    }
  },
  "model": "letsur/<MODEL_CODE>"
}

프로젝트의 opencode.json은 저장소에 커밋할 수 있지만 실제 키는 넣지 마세요. apiKey의 {env:LETSUR_API_KEY}를 유지하면 opencode가 실행 환경에서 키를 읽습니다.

아래 명령은 키 입력을 화면과 셸 히스토리에 남기지 않고 현재 셸 세션의 LETSUR_API_KEY에 저장합니다. 새 터미널을 열면 다시 설정해야 합니다.

printf 'Letsur API 키: '
IFS= read -rs LETSUR_API_KEY
printf '\n'
export LETSUR_API_KEY

모델 등록

custom provider에서 모델 선택기에 표시할 모델은 models에 직접 등록합니다. 쓰려는 모델을 에셋의 풀네임 그대로 등록하고, 최상위 model은 letsur/<모델 코드> 형식으로 맞춥니다.

모델 선택

  • 기본 모델 교체: 설정의 최상위 model 값을 letsur/<모델 코드> 형식으로 바꿉니다.
  • 세션 중 전환: TUI에서 /models를 실행해 Letsur Gateway 아래 등록한 모델 중에서 고릅니다.

연결 확인

(
  test -n "${LETSUR_API_KEY:-}" || { echo "LETSUR_API_KEY가 필요합니다." >&2; exit 1; }
  opencode run "ping"
)

모델 응답이 출력되면 provider와 키가 연결된 것입니다.

지원 범위와 제약

이 예시는 @ai-sdk/openai-compatible가 사용하는 Chat Completions 경로 기준입니다. Responses 전용 구성을 사용할 때는 opencode 공식 문서에 따라 provider package를 @ai-sdk/openai로 바꾸고, Letsur의 /v1/responses 지원 범위를 먼저 확인합니다.

문제 해결

증상먼저 확인할 것
모델 선택기에 모델이 없습니다provider.letsur.models에 에셋의 모델 코드를 등록했는지 확인합니다
키를 읽지 못합니다{env:LETSUR_API_KEY}와 실제 환경 변수 이름이 같은지 확인합니다
기본 모델을 열 수 없습니다최상위 model이 letsur/<모델 코드> 형식인지 확인합니다

설정 기준: opencode custom provider , Config , CLI 에서 provider package, 설정 경로, 환경 변수, run 및 /models 동작을 2026년 8월 7일에 확인했습니다.

마지막 업데이트