opencode-litellm

OpenCode CLI (v1 및 v2) 및 데스크톱 + LiteLLM 제공자를 제로 설정으로 연결합니다.

OpenCode V1 + V2

Powered by LiteLLM

npm downloads

CI

License: MIT

TypeScript

PRs Welcome

실행 중인 LiteLLM 프록시를 자동 감지하고, /v1/models에서 모든 모델을 가져와 OpenCode에 등록합니다.
수동으로 관리할 필요가 없습니다. 재시작 루프도 없고, 예상치 못한 문제도 없습니다.

Quickstart · Configuration · How it works · FAQ · Contributing

npm 패키지: opencode-plugin-litellm  ·  GitHub 저장소: yuseferi/opencode-litellm
스코프가 없는 opencode-litellm npm 이름은 이미 다른 작성자에 의해 사용 중입니다.

✅ OpenCode V1 + V2 지원: OpenCode 2.0.19는 네이티브 Plugin.define, 제공자 레지스트리 모델 발견, 인프로세스 새로 고침을 사용합니다. OpenCode **1.18.29+**는 레거시 server() 진입점을 사용합니다. 이 패키지는 두 버전 모두를 지원합니다.

✨ 왜 이 플러그인인가?

LiteLLM 프록시가 노출하는 모든 모델에 대해 opencode.json의 models 블록을 유지하는 것은 번거롭습니다. model_list에 새 항목이 추가될 때마다 설정 편집, 재시작, 그리고 컨텍스트 전환이 필요합니다.

opencode-litellm은 이 루프를 완전히 제거합니다. 플러그인 설정 중 LiteLLM 프록시를 쿼리하고 발견된 모델을 OpenCode의 제공자 레지스트리에 등록합니다. 새 모델은 V2 제공자 API를 통해 인프로세스(in-process)로 새로 고쳐지며, V1은 기존의 config-hook 동작 방식을 유지합니다.

🚀 빠른 시작 (Quickstart)

V2 호환 릴리스가 게시되면 CLI에서 플러그인을 설치하고 공유 백그라운드 서비스를 구성하세요. OpenCode 2 실행 파일 이름이 opencode2인 경우, 아래의 opencode 대신 사용하세요.

opencode plugin add opencode-plugin-litellm
opencode service set env LITELLM_BASE_URL https://litellm.internal.example.com/v1
opencode service set env LITELLM_API_KEY YOUR_API_KEY

그런 다음 OpenCode를 열고 litellm/... 아래에서 발견된 모델을 선택하세요.

RFC 상태: OpenCode 2 지원은 아직 게시된 npm 패키지에 포함되지 않았습니다. 현재는 plugin add가 이 RFC 구현이 아닌 이전 릴리스를 설치합니다.

포트 4000의 로컬 LiteLLM 프록시의 경우, 기본 URL을 생략할 수 있으며 플러그인이 이를 자동으로 감지합니다. 구성 섹션에서도 opencode.json에 제공자를 직접 구성하는 방법을 보여줍니다.

🎯 기능 (Features)

⚙️ 구성 (Configuration)

최소 설정 (권장) (Minimal config (recommended))

LiteLLM 프록시를 가리키면 플러그인이 모든 모델을 자동으로 발견합니다:

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["opencode-plugin-litellm@latest"],
...

명시적 제공자 (사용자 정의 URL 또는 인증) (Explicit provider (custom URL or auth))

어떤 모델도 나열할 필요가 없습니다. 플러그인이 여전히 /v1/models에서 자동으로 모델을 발견합니다. 이 형식은 기본 URL이 아니거나 API 키를 전달해야 할 때만 사용하세요:

이것이 전체 설정입니다. LiteLLM의 model_list에 있는 모든 모델이 선택기(picker)에 표시됩니다.

LiteLLM 제공자에서 명시적으로 settings.baseURL을 지정하면, 이는 LITELLM_BASE_URL보다 우선합니다. 둘 다 설정되지 않은 경우, 플러그인은 일반적인 로컬 포트를 확인합니다.

OpenCode 1.18.29 이상

이 패키지는 또한 이전 버전의 OpenCode 1 설치를 위한 V1 서버 진입점(entrypoint)을 노출합니다. 다음 V1 plugin / provider 구성 형태를 유지하세요:

{
  "plugin": ["opencode-plugin-litellm@latest"],
  "provider": {
...

예시: 튜닝 엔진을 통한 관리되는 상위(upstream) 경로

팀에서 정책, 추적(traces), 승인 및 사용 가시성을 위해 모델 트래픽을 Tuning Engines를 통해 라우팅하는 경우, 이를 LiteLLM 구성의 OpenAI 호환 상위 엔드포인트로 추가하세요. 플러그인은 다른 model_list 항목과 마찬가지로 LiteLLM에서 별칭(alias)을 자동으로 발견합니다:

model_list:
  - model_name: te-gpt-5.4-mini
    litellm_params:
...

그런 다음 이 키를 LiteLLM에 노출하고 OpenCode 구성은 동일한 LiteLLM 프록시에 연결된 상태로 유지하세요:

export TUNING_ENGINES_API_KEY=sk-te-...
litellm --config config.yaml --port 4000
opencode

OpenCode와 이 플러그인은 여전히 모델 발견 및 선택기 연결을 담당합니다. Tuning Engines는 관리되는 제어 평면(governed control plane)으로서 상위 모델 경로에 위치합니다.

개별 모델 재정의 또는 큐레이션 (선택 사항)

만약 선택기에서 모델 이름을 바꾸거나 메타데이터를 수동으로 큐레이션하고 싶다면, models 아래에 추가하세요. 플러그인은 사용자의 항목을 유지하며, 이미 정의되지 않은 키를 가진 발견된 모델만 주입합니다:

{
  "providers": {
    "litellm": {
...

여기서 openai/gpt-4o는 사용자 지정 이름을 유지하고, 프록시의 다른 모든 모델은 여전히 자동으로 발견되어 추가됩니다.

추론 모델 및 노력 변형 (Reasoning models and effort variants)

발견된 모든 모델(추론 등급 포함)은 단일 LiteLLM 제공자 아래에 등록되며 /v1/chat/completions을 통해 호출됩니다.

LiteLLM이 모델별 추론 노력(per-model reasoning-effort) 지원을 보고하면, 플러그인은 이를 OpenCode 변형으로 자동 노출합니다. 명시적인 reasoning_effort_levels (또는 supports_reasoning_efforts) 목록은 빈 목록을 포함하여 우선권을 가집니다. 그렇지 않은 경우, 모델별 supports_*_reasoning_effort 플래그가 검색을 활성화합니다: low, medium, 및 high는 명시적으로 비활성화되지 않는 한 포함되며, none, minimal, xhigh, max와 같은 선택적 레벨은 명시적인 true를 요구합니다. 이는 GPT-6 Astra의 xhigh/max 플래그와 같이 희소한 메타데이터를 보유하면서도 기본 레벨을 잃지 않도록 처리합니다. 추론 지원이 알려지지 않은 경우, supports_reasoning: true만으로는 레벨이 추론되지 않으며, 부정(negative) 노력 플래그만으로도 마찬가지입니다. 또한, supported_openai_params 목록에 reasoning_effort나 reasoning이 모두 포함되지 않으면 추론된 변형도 억제됩니다. 메타데이터는 model_info에서 읽고, 누락되거나 null인 값은 litellm_params로 폴백(fallback)합니다.

명시적인 노력 목록이 없는 경우, 알려진 GPT-5 Pro의 제한 사항도 적용됩니다: GPT-5 Pro는 high으로 제한되며, GPT-5.2 Pro / GPT-5.4 Pro는 medium, high, 그리고 명시적으로 지원되는 xhigh로 제한됩니다. 이러한 제한은 업스트림 모델 키 또는 litellm_params.model을 사용하며, 제공자 접두사 및 날짜가 지정된 스냅샷을 포함하므로 배포 별칭(deployment aliases)도 작동합니다. 명시적인 노력 목록이 이 폴백을 재정의할 수 있습니다.

각 변형은 보고된 레벨로 reasoningEffort를 설정하므로, 모든 항목을 직접 관리하지 않고도 모델 선택기에서 노력 레벨 간에 전환할 수 있습니다.

참고: OpenAI의 추론 계층 모델(gpt-5, o1, o3, o4)은 /v1/chat/completions에서 reasoning_effort와 함수 도구(function tools)를 결합하는 요청을 거부합니다. 이 오류가 발생하면 LiteLLM 측에서 수정해야 합니다 — 예를 들어 해당 모델에 대해 Responses API를 활성화하거나 (litellm_params의 use_responses_api: true), OpenCode에서 해당 모델의 reasoningEffort를 설정하지 않도록 두십시오. 자세한 내용은 아래 FAQ 항목을 참조하십시오.

인증(Authentication)

LiteLLM 프록시가 마스터 키를 요구하는 경우, 다음 두 가지 방법 중 하나로 노출합니다:

느린 프록시 (LITELLM_REQUEST_TIMEOUT_MS)

각 검색 요청(v1/models, v1/model/info)은 기본적으로 15초로 제한됩니다. 데이터베이스에 많은 모델이 정의된 프록시 또는 LiteLLM 앞에 게이트웨이가 있는 경우 합법적으로 더 오래 걸릴 수 있습니다. 다음을 사용하여 예산을 늘리세요:

export LITELLM_REQUEST_TIMEOUT_MS=60000

전반적인 검색 제한은 이에 비례하여 조정됩니다(최대 20초 및 요청 시간 초과 + 5초). 따라서 느린 프록시가 시작을 무기한으로 차단하지는 않지만, 도중에 끊어지지도 않습니다. 유효하지 않은 값은 기본값으로 폴백합니다.

사용자 지정 헤더 (Cloudflare Access, API 게이트웨이)

LiteLLM 프록시가 Cloudflare Access 또는 추가 HTTP 헤더를 요구하는 다른 게이트웨이 뒤에 있는 경우, 제공업체의 headers 맵을 사용하세요:

{
  "providers": {
    "litellm": {
...

이러한 헤더는 플러그인이 모델 검색(상태 검사 및 /v1/models) 중에 보내는 모든 요청에 포함됩니다. Cloudflare Access 서비스 토큰을 얻으려면 Cloudflare 문서를 따르세요.

하나의 프록시를 여러 제공업체로 분할 (includeModels / excludeModels)

LiteLLM 카탈로그가 서로 다른 팀이나 환경의 명명 규칙을 혼합하는 경우(예: prod/* 및 staging/*), 두 개의 OpenCode 제공업체를 동일한 프록시에 연결하고 각각이 자신의 슬라이스만 노출하도록 할 수 있습니다:

{
  "providers": {
    "litellm": {
...

• includeModels가 먼저 평가되며, 적어도 하나의 패턴과 일치하는 ID만 유지됩니다. 이를 생략하면 모든 모델이 유지됩니다.
• excludeModels는 나중에 평가되며, includeModels보다 항상 우선합니다.
• 패턴은 *(모든 문자열)만 지원하며, 그 외의 모든 것은 리터럴로 매칭되므로, gpt-4.1과 같은 ID의 점(.)은 이스케이프할 필요가 없습니다.
• 필터링은 온디스크 캐시가 쓰여지기 전에 발생하므로, 각 제공업체의 캐시된 뷰는 자체 필터를 준수합니다.
• 이름이 litellm-으로 시작하는 제공업체 ID는 자동으로 인식됩니다. 다른 ID를 가진 제공업체를 표시하려면 settings.litellm: true를 추가하십시오.

기능 플래그 수정 (modelCapabilities)

모델 분류(도구 호출 배지, 첨부 파일, 추론, 입력 모달리티)는 LiteLLM이 /v1/model/info를 통해 보고하는 기능 플래그에 의존합니다. 프록시가 해당 엔드포인트를 노출하지 않거나 배포 환경과 일치하지 않는 플래그를 보고하는 경우, 모델 ID별로 플래그를 재정의할 수 있습니다:

{
  "providers": {
    "litellm": {
...

• 재정의는 프록시가 보고한 내용 위에 적용되며, 명시적인 false가 우선합니다. 즉, 프록시가 한 번도 보고하지 않은 플래그라도 동일하게 강제할 수 있습니다.
• 키는 /v1/models에 나타나는 정확한 모델 ID입니다(글롭이 아님).
• 재정의된 플래그는 네이티브로 보고된 것과 완전히 동일하게 선택기(picker)로 흘러가며, 조정된 뷰가 모델 캐시에 영구 저장됩니다.
• /v1/model/info가 모달리티 플래그를 보고하지 않으면, 발견된 채팅 모델은 텍스트 전용으로 등록됩니다. 이는 OpenCode의 텍스트 전용 배포 환경에서의 이미지 지원 폴백(fallback)을 방지합니다. 멀티모달 프로젝터가 작동하는 경로에는 supports_vision: true를 명시적으로 설정하십시오.
• modelCapabilities (또는 includeModels/excludeModels)를 변경하면 다음 시작 시 새로운 발견이 이루어집니다. 캐시는 해당 구성에 의해 범위가 지정되므로, 선택기는 새로운 플래그를 즉시 반영합니다.