opencode

시작 전 준비

opencode는 OpenAI 호환 엔드포인트를 모델 연결 설정인 provider로 등록합니다. 게이트웨이를 provider 하나로 추가하고, 사용할 모델을 그 아래에 나열합니다.

• AI 게이트웨이 API 키

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

• 모델 코드

  이 가이드의 예제에 사용할 Chat Completions 지원 모델을 에셋에서 고르고 정확한 코드를 확인합니다.

• opencode CLI

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

npm i -g opencode-ai

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

연결 설정

provider 등록

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

models의 키와 최상위 model 값에는 같은 <MODEL_CODE>를 사용합니다.

{
  "$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>"
}

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

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

모델 등록

모델 선택

• 기본 모델 교체: 설정의 최상위 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 패키지를 @ai-sdk/openai로 바꾸고, 선택한 모델의 Responses 지원 여부와 Responses 요청 형식을 먼저 확인합니다.

문제 해결

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