OpenCode provider 또는 model을 찾을 수 없음: 진단 가이드

OpenCode의 제공업체 또는 모델을 찾을 수 없음 오류가 발생하면 먼저 선택한 모델을 OpenCode가 실제로 로드한 제공업체 및 모델 ID와 일치시키세요. 참조는 일반적으로 providerId/modelId 형식입니다. 올바른 API 키로는 철자가 틀린 ID, 선언되지 않은 사용자 지정 모델 또는 실행 중인 프로세스가 읽지 않는 구성 파일을 수정할 수 없습니다.

단순히 “제공업체 문제”라는 문구가 아니라 오류를 따라가세요

공식 문제 해결 가이드는 모델을 찾을 수 없음 오류에서 모델 참조를 확인하도록 안내합니다. 제공업체 소스에서 조회는 제공업체 항목과 해당 모델 맵을 모두 확인합니다. 동일한 오류가 어댑터의 모델 누락 오류를 감쌀 수도 있습니다. 자격 증명을 변경하거나 크레딧을 추가로 구매하기 전에 정확한 메시지를 캡처하세요.

1. 버전과 선택한 모델 식별

실패가 발생한 프로젝트에서 다음 검사를 실행하세요. 데스크톱 애플리케이션이 다른 서버를 사용하는 경우 해당 서버의 버전과 구성을 이 터미널 설치와 비교하세요:

opencode --version
opencode models
opencode auth list

목록에서 전체 모델 참조를 찾은 다음 선택 항목과 문자 단위로 비교하세요. 제공업체 접두사는 ID의 일부입니다. 사용자 지정 게이트웨이를 통해 제공되는 모델은 이름에 Claude가 포함되어 있다는 이유만으로 기본 제공 Anthropic 제공업체가 되지 않습니다.

저장된 자격 증명을 원격 인증이 성공했다는 증거로 해석하지 마세요. 저장된 자격 증명은 로컬에 자격 증명이 존재한다는 사실만 나타내며, 요청이 이루어질 때 엔드포인트가 이를 여전히 수락해야 합니다.

2. 제공업체/모델 조합 수정

이 예제는 v1 제공업체 형식을 사용하며 세 가지 일치하는 ID를 보여 줍니다. 참조된 환경 변수를 OpenCode를 시작하는 프로세스에서 설정하거나 문서화된 자격 증명 흐름을 사용하세요. 관련 필드를 구성에 병합하고 관련 없는 설정을 덮어쓰지 마세요:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "kunavo/claude-sonnet-5",
  "provider": {
    "kunavo": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Kunavo",
      "options": {
        "baseURL": "https://api.kunavo.com/v1",
        "apiKey": "{env:KUNAVO_API_KEY}"
      },
      "models": {
        "claude-sonnet-5": {
          "name": "Claude Sonnet 5"
        }
      }
    }
  }
}

여기서 kunavo는 제공업체 키이고 claude-sonnet-5는 모델 키입니다. 따라서 선택 항목은 kunavo/claude-sonnet-5입니다. anthropic/claude-sonnet-5를 선택하면 다른 제공업체가 선택되고, Kunavo/Claude Sonnet 5를 선택하면 조회 키 대신 표시 이름이 사용됩니다. 둘 다 위에 표시된 항목을 참조하지 않습니다.

사용자 지정 제공업체에 /connect와 Other를 사용할 때는 동일한 제공업체 ID를 입력하세요. 자격 증명만으로는 모델 카탈로그가 정의되지 않습니다. 어댑터도 확인하세요. 여기 표시된 v1 호환 어댑터는 Chat Completions를 사용하며, Responses 엔드포인트에는 적절한 어댑터가 필요합니다.

3. v1과 v2 구성을 분리하여 유지

v2 제공업체 문서에서는 v1의 provider, npm, options 대신 providers, package, settings를 사용합니다. 앞의 블록을 v2 구성에 변경 없이 복사하지 말고 버전에 맞는 설정을 사용하세요.

v2에서는 모델의 맵 키가 업스트림 modelID와 다를 수도 있습니다. 맵에 coder가 포함되고 업스트림 모델 upstream/coder-v2를 전송한다면 제공업체 company에 대해 company/coder를 선택하세요. 선택 항목을 업스트림 이름으로 변경하면 구성된 별칭을 우회하게 됩니다.

4. 어떤 구성이 우선하는지 확인

OpenCode는 구성 소스를 병합합니다. 프로젝트 파일이 전역 모델을 재정의할 수 있으며, 사용자 지정 경로, 인라인 구성 및 관리형 설정도 영향을 줄 수 있습니다. 실패한 프로젝트의 파일, 전역 구성 및 설정된 재정의를 검사하세요. 제공업체 허용 목록이나 비활성화된 제공업체 항목도 확인하세요.

한 번에 하나의 대상 변경만 수행하고 영향을 받는 프로세스를 다시 시작한 뒤 모델을 다시 나열하세요. 이제 모델을 사용할 수 있지만 첫 요청에서 HTTP 오류가 반환되면 새 오류를 따라가세요. 진단하는 동안 원본 파일과 세션 데이터를 유지하세요. 전체 데이터 디렉터리를 삭제하면 잘못된 모델 참조를 해결하지 못한 채 자격 증명과 기록이 제거될 수 있습니다.

짧은 요청으로 마무리

선택 항목이 확인되면 저장소 작업 전에 짧은 프롬프트 하나를 시도하세요. 의도한 제공업체가 요청을 수신하고 예상 모델을 기록하는지 확인하세요. 계속 실패한다면 버전, 정리된 구성, 정확한 오류 및 관련 로그 발췌를 수집하세요. 공유하기 전에 로그에서 키와 프로젝트 콘텐츠를 검토하세요.

Kunavo의 경우 OpenCode 통합 가이드를 계속 확인하고 사용량 기록을 확인하세요. 현재 Claude Sonnet 5 요금은 백만 토큰당 입력 $1.40, 출력 $7.00입니다. 클라이언트가 의도한 경로를 선택한 후에 가격 비교가 유용해집니다.

자주 묻는 질문

공식 문서와 제공업체 소스는 2026년 9월 17일에 확인했습니다. 이 예제는 구성 ID를 설명하며, 엔드투엔드 작업 벤치마크가 아닙니다.