OpenCode와 로컬 LLM 구성

Source: Dev.to

OpenCode에 사용자 정의 OpenAI‑호환 엔드포인트 추가

OpenCode는 현재 UI에서 간단한 “엔드포인트 직접 연결” 옵션을 제공하지 않습니다. 대신 미리 정의된 클라우드 제공자 목록과 함께 제공됩니다.
OpenCode는 OpenAI‑호환 API를 완전히 지원하므로, vLLM, LM Studio, 프록시가 있는 Ollama, 혹은 직접 만든 서버와 같은 호환 엔드포인트를 자유롭게 연결할 수 있습니다.

이 가이드는 로컬 vLLM 서버를 제공자로 연결하는 방법을 보여줍니다. 동일한 방법으로 모든 OpenAI‑호환 엔드포인트에 적용할 수 있습니다.

사전 요구 사항

• OpenCode가 설치되어 실행 중이어야 함
• OpenAI‑호환 엔드포인트가 실행 중이어야 함 (예: http://:8000/v1 주소의 로컬 vLLM 서버)

vLLM은 OpenAI의 Chat Completions API와 일치하는 /v1 API를 제공하므로, 바로 사용할 수 있는 백엔드입니다.

1. 제공자 인증 정보 저장

OpenCode는 인증 데이터를 ~/.local/share/opencode/auth.json에 보관합니다.

해당 파일이 없으면 새로 만들고 다음 항목을 추가합니다:

{
  "vllm": {
    "type": "api",
    "key": "sk-local"
  }
}

• vLLM은 API 키가 필요 없지만, OpenCode는 키가 존재하기를 기대합니다. 임의의 자리표시자 값(sk-local 등)이면 충분합니다.
• auth.json 파일이 이미 존재한다면, 기존 JSON에 vllm 블록을 병합하세요.

2. 제공자 설정 정의

~/.config/opencode/opencode.json을 생성하거나 편집합니다:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "vllm": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "vLLM (local)",
      "options": {
        "baseURL": "http://100.108.174.26:8000/v1"
      },
      "models": {
        "Qwen3-Coder-30B-A3B-Instruct": {
          "name": "My vLLM model"
        }
      }
    }
  },
  "model": "vllm/Qwen3-Coder-30B-A3B-Instruct",
  "small_model": "vllm/Qwen3-Coder-30B-A3B-Instruct"
}

주요 필드

• npm – @ai-sdk/openai-compatible는 OpenCode에 이 제공자를 OpenAI‑호환으로 취급하도록 알려줍니다.
• options.baseURL – 서버의 /v1 엔드포인트를 정확히 가리켜야 합니다.
• models – 키는 백엔드가 노출하는 모델 ID와 정확히 일치해야 합니다.
• model / small_model – OpenCode에서 사용할 기본 모델을 지정합니다.

3. OpenCode 재시작

OpenCode가 이미 실행 중이라면, 새로운 설정을 로드하기 위해 재시작합니다.

4. 사용자 정의 제공자 사용

이제 /model 명령(또는 UI 선택 목록)을 통해 사용자 정의 제공자와 모델을 선택할 수 있습니다. “vLLM (local) – My vLLM model” 항목이 사용 가능한 옵션 중에 표시됩니다.