opencode
게이트웨이 모델을 등록하고 작업에 맞게 선택하기
Chat Completions를 기준으로 provider와 모델을 등록하는 방법, Responses에 필요한 별도 설정과 지원 확인 사항을 안내합니다.
페이지 목차
시작 전 준비
설정을 마치면 opencode가 AI 게이트웨이를 provider로 사용해 모델을 호출합니다. provider 아래에 등록한 모델은 기본 모델로 지정하거나 세션 중에 선택할 수 있습니다. 예제 설정은 Chat Completions 경로를 기준으로 합니다.
- AI 게이트웨이 API 키
현재 사용할 수 있는 AI 게이트웨이 API 키를 준비합니다.
- 모델 코드
에셋에서 Chat Completions를 지원하는 모델의 정확한 코드를 확인합니다. 이 가이드의 예제는 이 API 형식을 사용합니다.
- opencode CLI
OpenCode 2 CLI를 설치합니다. 이 가이드의 설정 형식은 OpenCode 2를 기준으로 합니다.
opencode CLI를 아직 설치하지 않았다면 다음 명령으로 설치합니다. 이전 패키지 opencode-ai는 OpenCode 1을 설치하며, OpenCode 1은 이 가이드와 설정 형식이 다릅니다.
npm install -g @opencode/cliopencode에 넣을 값은 아래 단계에 모두 있습니다. API 형식별 기본 URL과 인증 헤더 전체는 인증과 기본 URL에 정리돼 있습니다.
연결 설정
opencode에 OpenAI 호환 엔드포인트를 연결하려면 provider를 등록합니다. 게이트웨이를 provider 하나로 추가하고, 사용할 모델을 그 아래에 나열합니다.
provider 등록하기
전역 설정은
~/.config/opencode/opencode.json에, 프로젝트별 설정은 프로젝트 루트의opencode.json또는.opencode/opencode.json에 작성합니다. 확장자는.json과.jsonc를 모두 쓸 수 있습니다.같은 항목이 여러 파일에 있으면 관리자가 배포한 시스템 설정,
.opencode폴더 안의 설정, 프로젝트 루트의 설정, 전역 설정 순서로 우선합니다.아래 예제를 고칠 때는 다음 규칙을 지키세요.
- provider는
providers아래에 등록합니다. 이전 형식의provider키는 더 이상 권장되지 않습니다. - 사용할 모델은
models에 직접 등록하고, 키에는 에셋의 정확한 모델 코드를 씁니다. - 최상위
model에는letsur/<모델 코드>형식으로 씁니다. - 예제의 두
<MODEL_CODE>를 같은 모델 코드로 바꿉니다.
{ "$schema": "https://opencode.ai/config.json", "providers": { "letsur": { "env": ["LETSUR_API_KEY"], "package": "@opencode/ai/providers/openai-compatible", "name": "Letsur Gateway", "settings": { "baseURL": "https://gw.letsur.ai/v1" }, "models": { "<MODEL_CODE>": { "name": "Letsur model" } } } }, "model": "letsur/<MODEL_CODE>" }- provider는
API 키 환경 변수 설정하기
실제 키를 명령어나 설정 파일에 직접 입력하지 마세요프로젝트의
opencode.json은 저장소에 커밋될 수 있습니다.env에는 환경 변수 이름LETSUR_API_KEY만 지정합니다.실행 환경에서
LETSUR_API_KEY환경 변수에 AI 게이트웨이 API 키를 설정합니다.변수를 설정하기 전에 시작된 opencode 서버는 키를 읽지 못합니다요청은 opencode 서버 프로세스가 보내므로 이 프로세스가 변수를 읽을 수 있어야 합니다. opencode는 기본적으로 사용자 계정마다 공유 백그라운드 서버 하나를 찾거나 시작합니다. 이 서버가 변수를 설정하기 전에 시작됐다면 변수를 설정한 터미널에서
opencode --standalone으로 별도 서버를 사용해 실행하세요.
모델 선택
- 기본 모델 교체: 사용할 모델이
models에 등록되어 있는지 확인한 뒤, 최상위model값을letsur/<모델 코드>형식으로 바꿉니다. - 세션 중 전환:
opencode로 TUI를 열고/models를 실행해 등록한 모델을 선택합니다. 이 선택은 현재 세션에만 적용되며 설정 파일을 바꾸지 않습니다. - 명령 한 번에 지정:
opencode run에--model옵션을 지정하면 기본 모델을 바꾸지 않고 그 실행에만 다른 모델을 사용합니다.
연결 확인
LETSUR_API_KEY가 설정된 실행 환경에서 다음 명령을 실행합니다.
opencode run "ping"opencode는 설정한 기본 모델을 사용할 수 없으면 사용 가능한 다른 모델로 대체합니다. 등록한 게이트웨이 모델이 응답했는지 확인하려면 모델을 직접 지정해 다시 실행합니다.
opencode run --model "letsur/<MODEL_CODE>" "ping"모델 응답이 출력되면 opencode가 게이트웨이를 거쳐 모델을 호출한 것입니다. 실제 작업에 사용할 도구 호출은 별도로 확인합니다.
지원 범위와 제약
이 가이드의 예제는 @opencode/ai/providers/openai-compatible 패키지가 사용하는 Chat Completions 경로를 기준으로 합니다. Responses 전용 구성을 사용하려면 다음 순서를 따르세요.
- 선택한 모델의 Responses 지원 여부를 확인합니다.
- Responses 요청 형식을 확인합니다.
- opencode 공식 문서에 따라 provider 패키지를
@opencode/ai/providers/openai-compatible/responses로 바꿉니다.
opencode 카탈로그에 없는 모델을 직접 등록하면 opencode는 JSON 도구 호출 지원, 텍스트와 이미지 입력, 컨텍스트 200,000 토큰과 출력 32,000 토큰을 기본값으로 가정합니다. 이 기본값은 opencode가 모델에서 감지한 값이 아니므로, 모델의 실제 한도를 알면 models 항목의 capabilities와 limit에 지정합니다.
문제 해결
| 증상 | 다음 행동 |
|---|---|
| 모델 선택기에 모델이 없습니다 | providers.letsur.models에 에셋의 모델 코드를 등록했는지 확인합니다 |
| opencode가 키를 읽지 못합니다 | env에 지정한 LETSUR_API_KEY 환경 변수가 opencode 서버 프로세스의 실행 환경에 설정되어 있는지 확인합니다. 공유 백그라운드 서버가 변수를 설정하기 전에 시작되었다면 변수를 설정한 터미널에서 opencode --standalone으로 별도 서버를 사용해 실행합니다 |
401 응답이 반환됩니다 | 키 값과 키 상태(비활성 또는 만료)를 확인합니다 |
| opencode가 기본 모델을 불러오지 못하거나 다른 모델이 응답합니다 | 최상위 model이 letsur/<모델 코드> 형식이고 같은 모델 코드가 models에 등록되어 있는지 확인합니다 |
Model unavailable 오류가 표시됩니다 | provider가 활성화되어 있는지, 지정한 모델 코드가 models의 키와 정확히 같은지 확인합니다 |
그 밖의 오류는 오류 type별 대응에서 확인합니다.
설정 기준: Providers , Config , Models , CLI , Intro , 설정 스키마 의 provider 키와 패키지, 설정 파일 위치와 우선순위, 환경 변수, 모델 선택과 기본값, opencode run 동작, 설치 패키지를 2026년 11월 13일에 확인했습니다. 이 확인에는 렛서 게이트웨이와의 실제 연동 시험이 포함되지 않습니다.