OpenCode 프로바이더: 모델, 키, 설정을 확인하는 7가지 점검

OpenCode 프로바이더를 찾는 사용자는 어떤 서비스를 선택할지, 외부 프로바이더를 추가할지, OpenAI 호환 엔드포인트가 작동하는지, 프로바이더는 보이는데 모델이 없는 이유를 알고 싶을 수 있습니다. 가격, 모델 ID, 인증 방식은 바뀌므로 고정된 서비스 목록보다 판단 순서가 더 오래 유용합니다.

OpenCode 공식 Providers 문서는 인증 정보, 설정, Zen과 Go 서비스, 프로바이더 디렉터리를 함께 다룹니다. 이 글은 계층을 구분하고, 최소 연결을 선택하고, 모델 ID를 확인하고, 쓰기 작업 전에 증거를 남기는 실제 순서를 추가합니다.

프로바이더는 모델 서비스로 가는 경로입니다. 모델은 서비스가 제공하는 구체적인 능력이고 인증 정보는 요청 권한을 증명합니다. 세 가지를 하나의 설정처럼 다루면 증상이 헷갈립니다. 올바른 키는 잘못된 모델 ID를 고치지 못하고 모델이 보인다고 인증이 유효하다는 뜻도 아닙니다.

설정 범위는 네 번째 문제입니다. 프로젝트 파일에서는 작동하지만 전역 파일에서는 작동하지 않을 수 있고 관리 설정이 수정 내용을 덮어쓸 수도 있습니다. 전체 설정 파일을 공유하기보다 파일, 범위, 프로바이더 이름, 모델 ID, 확인 날짜를 기록하세요.

실용적인 경로는 네 가지입니다. OpenCode의 Go와 OpenCode의 Zen은 각각 요금제와 모델 전제가 있는 공식 서비스입니다. 호스팅된 외부 프로바이더는 팀의 결제, 지역 제어, 모델 카탈로그가 이미 정해져 있을 때 적합합니다. OpenAI 호환 또는 로컬 엔드포인트는 유연하지만 URL, 모델 검색, 런타임, 진단을 더 직접 확인해야 합니다.

디렉터리의 이름만 보고 선택하지 마세요. 예측 가능한 월 비용, 사용량 제어, 데이터 위치, 오프라인 사용, 품질, 지연 시간, 기존 운영 서비스 중 무엇이 우선인지 먼저 정합니다. 모델 목록이 불안정하거나 OpenCode가 실행되는 환경에서 엔드포인트를 확인할 수 없다면 저렴하다는 이유만으로 충분하지 않습니다.

공식 설정 구조에서는 사용자 지정 프로바이더를 provider 아래에 둡니다. npm 어댑터, 옵션, 인증 변수, 모델 맵은 서비스마다 다릅니다. 제공자의 공식 문서를 먼저 읽고 이해한 필드만 복사하며 엔드포인트와 어댑터를 선택한 이유를 기록하세요.

비밀값은 저장소 밖에서 관리합니다. OAuth, 환경 변수, 플랫폼 인증 정보 저장소를 사용하고 실제 API 키를 opencode.json, 스크린샷, 셸 기록, 공유 세션에 넣지 마세요. 로그에 노출되었다면 계속 진행하기 전에 키를 교체합니다.

테스트할 때는 프로바이더를 한 번에 하나만 추가하세요. 변경을 작게 유지하면 schema 문제, 서비스 장애, 롤백을 구분할 수 있습니다. 새 블록을 제거하고 기존 모델로 돌아간 다음 알려진 요청을 반복합니다.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "my-provider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "provider-demo",
      "options": { "baseURL": "https://api.provider.test/v1" },
      "models": { "model-id": { "name": "Model name" } }
    }
  }
}

프로바이더 설정은 OpenCode가 실제 모델을 찾고 작은 요청을 완료해야 끝납니다. 최신 프로바이더 문서에서 ID와 인증 방식을 확인하고 /models로 선택 가능한 모델을 확인하세요. 여러 변형이 있다면 작업의 컨텍스트, 도구, 지연, 비용에 맞는 하나부터 시작합니다.

첫 요청은 읽기 전용이면서 비교하기 쉬워야 합니다. 작은 로컬 파일을 설명하게 하거나 명령을 실행하지 않고 다음 검증 명령만 제안하게 하세요. 응답 완성도, 도구 사용 가능 여부, 시간, 사용 모델을 기록하고 그 후에 편집이나 외부 쓰기를 테스트합니다.

1. 범위 확인전역, 프로젝트, 사용자 지정 경로, 관리 설정을 구분합니다.
2. 키 보호OAuth, 환경 변수, 프로바이더 저장소를 사용합니다.
3. 프로바이더 확인ID, 어댑터, 엔드포인트, 공식 절차를 대조합니다.
4. 모델 확인표시 이름이 아니라 정확한 모델 ID를 사용합니다.
5. 모델 목록 확인선택기나 공식 `/models` 절차를 실행합니다.
6. 읽기 전용 테스트작은 프롬프트를 보내 예상 결과와 비교합니다.
7. 롤백 기록정상 설정, 결과, 최소 되돌리기 절차를 남깁니다.

인증, 검색, 모델, 전송을 분리하면 오류를 더 쉽게 고칠 수 있습니다. 401이나 OAuth 반복은 인증 정보나 scope, 프로바이더가 보이지 않는 문제는 설정 범위나 schema, 모델이 없는 문제는 카탈로그나 ID, 검색 후의 타임아웃은 네트워크, 프록시, 지역, 서비스 상태를 가리킬 가능성이 큽니다.

테스트마다 한 변수만 바꾸세요. 공식 절차로 엔드포인트를 확인하고, OpenCode가 읽는 파일을 확인한 뒤, 모델을 나열하고 마지막에 프롬프트를 테스트합니다. 하나의 고장을 진단하려고 프로바이더를 계속 추가하면 목록과 로그를 읽기 어려워집니다.

예측 가능한 구독과 한도가 필요하면 OpenCode의 Go, 선택된 카탈로그와 사용량 결제가 중요하면 Zen을 검토할 수 있습니다. 결제, 규정 준수, 지역, 특정 모델이 중요하면 호스팅된 외부 프로바이더가 적합합니다. 오프라인이나 호환 게이트웨이가 필요하고 런타임을 직접 책임질 수 있다면 로컬/OpenAI 호환 엔드포인트를 선택할 수 있습니다. 이는 적합성 판단이지 영구 순위가 아닙니다.

프로바이더는 개인정보 전제도 바꿉니다. CLI는 로컬에서 실행되어도 요청은 선택한 모델 서비스로 전송될 수 있습니다. 정책을 읽고 비밀값과 불필요한 고객 데이터를 보내지 않으며 첫 테스트는 운영 저장소 밖에서 진행합니다. 모델 설정, Ollama 연결, Go와 Zen 페이지가 인접 주제를 다루므로 이 페이지에서는 중복하지 않고 연결합니다.

넓은 OpenCode 프로바이더 검색에서 중요한 결과는 고정된 승자 목록이 아니라 재현 가능한 연결입니다. 디렉터리, 모델, 가격, 한도, 로그인 방식은 바뀌므로 설정하는 날 공식 문서를 다시 확인하고 날짜를 기록하세요.