OpenCode 빠른 시작

OpenCode 빠른 시작

이 튜토리얼은 OpenCode를 기존 LiteLLM 인스턴스에 연결하고 모델 간에 전환하는 방법을 보여줍니다.

info

이 통합을 통해 중앙 집중식 인증, 사용량 추적, 비용 통제와 함께 OpenCode를 통해 LiteLLM이 지원하는 어떤 모델이든 사용할 수 있어요.

비디오 안내

전제 조건

• 이미 구성되어 실행 중인 LiteLLM(예: http://localhost:4000)
• LiteLLM API 키

설치

1단계: OpenCode 설치

선호하는 설치 방법을 선택하세요:

• One-line install (recommended)
• NPM
• Homebrew

curl -fsSL https://opencode.ai/install | bash

npm install -g opencode-ai

brew install sst/tap/opencode

설치 확인:

opencode --version

2단계: LiteLLM Provider 구성

OpenCode 구성 파일을 만드세요. 필요에 따라 여러 위치에 배치할 수 있어요:

구성 위치:

• Global: ~/.config/opencode/opencode.json(모든 프로젝트에 적용)
• Project: 프로젝트 루트의 opencode.json(프로젝트별 설정)
• Custom: OPENCODE_CONFIG 환경 변수 설정

~/.config/opencode/opencode.json(전역 설정)을 만드세요:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "litellm": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LiteLLM",
      "options": {
        "baseURL": "http://localhost:4000/v1"
      },
      "models": {
        "gpt-5.6-terra": {
          "name": "GPT-5.6 Terra"
        },
        "claude-sonnet-5": {
          "name": "Claude Sonnet 5"
        },
        "deepseek-chat": {
          "name": "DeepSeek Chat"
        }
      }
    }
  }
}

tip

"models" 객체의 키(예: "gpt-5.6-terra", "claude-sonnet-5")는 LiteLLM 설정의 model_name 값과 일치해야 해요. "name" 필드는 OpenCode에서 별칭으로 나타나는 친숙한 표시 이름을 제공합니다.

모델이 이미지를 받아들이면 modalities 항목도 필요해요. image and vision input 활성화를 참고하세요.

3단계: LiteLLM Provider에 연결

OpenCode를 실행하세요:

opencode

API 키를 추가하세요:

/connect

그런 다음:

• Enter provider name: LiteLLM(설정의 "name" 필드와 일치해야 함)
• Enter your LiteLLM API key: LiteLLM master key 또는 virtual key

4단계: 모델 간 전환

OpenCode에서 실행하세요:

/models

LiteLLM 설정에서 아무 모델이나 선택하세요. OpenCode가 모든 요청을 LiteLLM 인스턴스를 통해 라우팅합니다.

고급 구성

모델 파라미터

컨텍스트 한도 같은 모델 파라미터를 커스터마이즈할 수 있어요:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "litellm": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LiteLLM",
      "options": {
        "baseURL": "http://localhost:4000/v1"
      },
      "models": {
        "gpt-5.6-terra": {
          "name": "GPT-5.6 Terra",
          "limit": {
            "context": 922000,
            "output": 128000
          }
        },
        "claude-sonnet-5": {
          "name": "Claude Sonnet 5",
          "limit": {
            "context": 1000000,
            "output": 128000
          }
        }
      }
    }
  }
}

이미지 및 비전 입력 활성화

OpenCode는 /v1/models 엔드포인트에서 모델 기능을 발견하지 않습니다. OpenAI 모델 목록 스키마에는 modalities 필드가 없어서 읽을 것이 없어요. 따라서 커스텀 @ai-sdk/openai-compatible provider 아래의 모델은 텍스트 전용 입력으로 폴백합니다.

이 효과는 클라이언트 측이고 조용히 발생해요: OpenCode는 모델의 선언된 입력 modalities를 확인하고 image가 없으면 요청이 전송되기 전에 이미지 첨부를 요청에서 제거합니다. LiteLLM은 이미지를 받지 못하고, 모델은 아무것도 붙여넣지 않은 것처럼 응답합니다.

비전 가능 모델 각각에 modalities를 OpenCode 설정에서 선언하세요:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "litellm": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LiteLLM",
      "options": {
        "baseURL": "http://localhost:4000/v1"
      },
      "models": {
        "claude-sonnet-5": {
          "name": "Claude Sonnet 5",
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        },
        "gpt-5.6-terra": {
          "name": "GPT-5.6 Terra",
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        },
        "deepseek-chat": {
          "name": "DeepSeek Chat"
        }
      }
    }
  }
}

deepseek-chat 같은 텍스트 전용 모델에서는 modalities를 두지 마세요. 이미지를 받을 수 없는 모델에 image 입력을 선언하면 실패 지점이 클라이언트에서 제공자로 옮겨집니다.

warning

LiteLLM config.yaml의 model_info 아래에 supports_vision: true를 설정해도 이 문제가 해결되지 않습니다. 그 플래그는 LiteLLM 자체의 라우팅과 비용 로직을 구동하며 /v1/models에 노출되지 않고, 노출돼도 OpenCode가 읽지 않아요. OpenCode 설정의 modalities만이 이것을 선언할 수 있는 유일한 곳입니다.

Auto Router 및 기타 모델 그룹

모델 그룹은 OpenCode에게 그저 또 다른 모델 이름일 뿐이므로, Auto Router 항목도 그 뒤의 모델들이 비전 가능하더라도 같은 선언이 필요해요:

{
  "models": {
    "smart-router": {
      "name": "Smart Router",
      "modalities": { "input": ["text", "image"], "output": ["text"] }
    }
  }
}

router가 선택할 수 있는 모든 등급(tier)이 이미지를 받아들일 때만 image 입력을 선언하세요. 한 등급이 텍스트 전용이라면, router가 그 등급에 도달했을 때 이미지가 포함된 요청이 실패합니다.

다중 제공자 설정

여러 LiteLLM 인스턴스를 구성하거나 다른 제공자와 섞을 수 있어요:

• Multiple LiteLLM Instances
• Mixed Providers

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "litellm-prod": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LiteLLM Production",
      "options": {
        "baseURL": "https://your-prod-instance.com/v1"
      },
      "models": {
        "gpt-5.6-terra": {
          "name": "GPT-5.6 Terra (Production)"
        }
      }
    },
    "litellm-dev": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LiteLLM Development",
      "options": {
        "baseURL": "http://localhost:4000/v1"
      },
      "models": {
        "gpt-5.6-terra": {
          "name": "GPT-5.6 Terra (Development)"
        }
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "litellm": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LiteLLM",
      "options": {
        "baseURL": "http://localhost:4000/v1"
      },
      "models": {
        "gpt-5.6-terra": {
          "name": "GPT-5.6 Terra via LiteLLM"
        },
        "claude-sonnet-5": {
          "name": "Claude Sonnet 5 via LiteLLM"
        }
      }
    },
    "openai": {
      "npm": "@ai-sdk/openai",
      "name": "OpenAI Direct",
      "models": {
        "gpt-5.6-terra": {
          "name": "GPT-5.6 Terra (Direct)"
        }
      }
    }
  }
}

예시 LiteLLM 설정

OpenCode와 잘 맞는 LiteLLM config.yaml 예시입니다:

model_list:
  # OpenAI models
  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY
  - model_name: gpt-5.6-luna
    litellm_params:
      model: openai/gpt-5.6-luna
      api_key: os.environ/OPENAI_API_KEY
  # Anthropic models
  - model_name: claude-sonnet-5
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY
  # DeepSeek models
  - model_name: deepseek-chat
    litellm_params:
      model: deepseek/deepseek-chat
      api_key: os.environ/DEEPSEEK_API_KEY

OpenCode 특정 파라미터 제거

OpenCode는 gpt-5.6-terra 같은 reasoning-capable 모델과 함께 reasoningSummary 파라미터를 보냅니다. 이 파라미터는 Chat Completions API에서 지원되지 않아 오류를 일으킬 수 있어요. reasoning이 활성화된 OpenCode에서 요청을 받을 model_list의 모든 모델 항목에 additional_drop_params를 추가하세요:

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY
      additional_drop_params: ["reasoningSummary"]

트러블슈팅

OpenCode not connecting:

• LiteLLM proxy가 실행 중인지 확인: curl http://localhost:4000/health
• OpenCode 설정의 baseURL이 LiteLLM 인스턴스와 일치하는지 확인
• /connect의 provider 이름이 설정과 정확히 일치하는지 확인

Authentication errors:

• LiteLLM API 키가 올바른지 확인
• LiteLLM 인스턴스에 인증이 올바르게 구성됐는지 확인
• API 키가 사용하려는 모델에 접근 권한이 있는지 확인

Model not found:

• OpenCode 설정의 모델 이름이 LiteLLM model_name 값과 일치하는지 확인
• 자세한 오류 메시지를 위해 LiteLLM 로그 확인
• 모델이 LiteLLM 인스턴스에 올바르게 구성됐는지 확인

Configuration not loading:

• 구성 파일 경로와 권한 확인
• JSON validator로 JSON 문법 검증
• $schema URL에 접근 가능한지 확인

Images and screenshots are ignored:

• OpenCode는 커스텀 OpenAI 호환 제공자 모델을 텍스트 전용 입력으로 기본 설정하고, 전송 전에 이미지 첨부를 제거하므로 LiteLLM에 도달하는 요청에는 이미지가 없어요. OpenCode 설정에서 모델에 modalities를 선언하세요:

"claude-sonnet-5": {
  "name": "Claude Sonnet 5",
  "modalities": { "input": ["text", "image"], "output": ["text"] }
}

• LiteLLM config.yaml의 model_info: supports_vision: true는 여기서 효과가 없어요. image and vision input 활성화를 참고하세요.

Unknown parameter: 'reasoningSummary' error:

• OpenCode는 Chat Completions API에서 지원되지 않는 reasoningSummary 파라미터를 보냅니다. litellm_params의 각 영향받는 모델 항목에 additional_drop_params: ["reasoningSummary"]를 추가하세요:

- model_name: gpt-5.6-terra
  litellm_params:
    model: openai/gpt-5.6-terra
    api_key: os.environ/OPENAI_API_KEY
    additional_drop_params: ["reasoningSummary"]

팁

• 필요에 따라 설정에 모델을 더 추가하세요 - /models에 나타납니다.
• 모델 요구 사항이 다른 코드베이스에는 프로젝트별 설정을 사용하세요.
• OpenCode 요청을 실시간으로 보려면 LiteLLM proxy 로그를 모니터링하세요.

더 알아보기 (Learn more)

• OpenCode