OpenCode는 프로바이더 디렉터리를 통해 75개 이상의 LLM 프로바이더를 지원하지만, 커스텀 프로바이더는 여전히 중요합니다. 게이트웨이, 로컬 런타임, 내부 추론 엔드포인트를 추가하거나 아직 디렉터리에 없는 모델을 사용할 때 필요하기 때문입니다.

절차는 단순합니다. 인증 정보를 저장하고, 프로바이더 블록을 추가하고, OpenCode를 재시작한 다음 /models에서 모델을 선택하면 됩니다.

Haimaker를 연결하려는 건가요? 수동 설정은 건너뛰세요. npx -y @haimaker/connect --opencode를 실행하면 CLI가 프로바이더 블록을 작성하고 인증 정보를 자동으로 저장합니다(프로젝트 로컬 설정이 필요하면 --project를 추가하세요). 아래 안내는 모든 OpenAI 호환 프로바이더에 적용되는 일반적인 방법입니다. Ollama, LM Studio, 내부 게이트웨이, 아직 디렉터리에 없는 프로바이더까지 모두 같습니다. 한 줄 명령으로 처리하려면 connect 가이드를 참조하세요.

커스텀 프로바이더를 사용해야 할 때

모델이나 엔드포인트가 OpenCode의 내장 프로바이더 목록에 이미 등록되어 있지 않다면 커스텀 프로바이더를 사용하세요.

대표적인 활용 사례:

  • Haimaker - OpenAI 호환 게이트웨이를 통해 여러 모델 계열을 API 키 하나로 사용.
  • Ollama - http://localhost:11434/v1에서 실행되는 로컬 모델.
  • LM Studio - http://127.0.0.1:1234/v1에서 실행되는 로컬 모델.
  • 내부 게이트웨이 - 사내에서 호스팅하는 OpenAI 호환 엔드포인트.
  • 신규 프로바이더 - OpenCode 디렉터리에 반영되기 전에 OpenAI 호환 Chat API를 지원하는 모든 프로바이더.

프로바이더가 이미 OpenCode에 등록되어 있다면 내장 경로를 먼저 사용하세요. 커스텀 설정은 커스텀 base URL, 게이트웨이, 또는 기본 목록에 없는 모델이 필요할 때 가장 유용합니다.

1단계: 인증 정보 추가

현재 OpenCode 문서에서는 프로바이더 인증 정보를 등록할 때 opencode auth login를 사용하라고 안내합니다. 커스텀 OpenAI 호환 프로바이더의 경우 Other를 선택하고, 프로바이더 ID를 입력한 다음 API 키를 붙여넣으세요:

opencode auth login

설정 파일에서도 사용할 짧은 프로바이더 ID를 정하세요. 예시:

haimaker
ollama
mygateway

OpenCode는 인증 정보를 다음 위치에 저장합니다:

~/.local/share/opencode/auth.json

필요하면 이 파일을 직접 편집할 수도 있지만, opencode auth login를 사용하면 키 형식 오류를 방지할 수 있습니다.

2단계: 프로바이더 설정

OpenCode 설정 파일을 열거나 새로 만드세요. 환경에 따라 프로젝트의 opencode.json이거나 ~/.config/opencode/ 아래의 전역 파일일 수 있습니다.

인증 시 사용한 것과 동일한 프로바이더 ID로 provider 블록을 추가하세요. haimaker.ai를 예시로 들면 다음과 같습니다:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "haimaker": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Haimaker",
      "options": {
        "baseURL": "https://api.haimaker.ai/v1"
      },
      "models": {
        "z-ai/glm-4.6": {
          "name": "GLM 4.6"
        },
        "minimax/minimax-m2.5": {
          "name": "MiniMax M2.5"
        },
        "qwen/qwen3-coder": {
          "name": "Qwen3 Coder"
        }
      }
    }
  }
}

각 필드의 역할:

  • npm: SDK 어댑터. 모든 OpenAI 호환 API에는 @ai-sdk/openai-compatible를 사용하세요. OpenCode는 필요할 때 어댑터를 로드합니다.
  • name: OpenCode에 표시되는 이름입니다.
  • options.baseURL: 프로바이더 API의 base URL입니다. /v1 또는 프로바이더가 사용하는 버전 접두사로 끝나야 합니다.
  • models: OpenCode에서 사용하려는 모델 목록입니다. 키는 프로바이더 API가 completion 요청의 model 필드에서 받아들이는 값과 정확히 일치해야 합니다.

커스텀 프로바이더는 원하는 만큼 추가할 수 있으며, 각각 provider 아래 별도 항목으로 넣으면 됩니다.

3단계: 재시작 및 확인

프로바이더 설정을 변경한 경우 OpenCode를 재시작해야 반영될 수 있습니다. 완전히 종료한 후 다시 시작하고 다음을 실행하세요:

/models

프로바이더 이름과 설정한 모델 목록이 표시됩니다. 실제 코드에 적용하기 전에 하나를 선택해서 간단한 프롬프트를 보내보세요.

전체 예시: Haimaker 게이트웨이

여러 모델 계열을 하나의 OpenAI 호환 엔드포인트로 사용하려면 이 구성을 활용하세요:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "haimaker": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Haimaker",
      "options": {
        "baseURL": "https://api.haimaker.ai/v1"
      },
      "models": {
        "anthropic/claude-sonnet-4-6": {
          "name": "Claude Sonnet 4.6"
        },
        "openai/gpt-5.4-mini": {
          "name": "GPT-5.4 Mini"
        },
        "minimax/minimax-m2.5": {
          "name": "MiniMax M2.5"
        },
        "qwen/qwen3-coder": {
          "name": "Qwen3 Coder"
        }
      }
    }
  }
}

이 구성이 효과적인 이유: OpenCode는 프로바이더 하나만 인식하고, Haimaker가 여러 업스트림 모델 계열로의 접근을 처리합니다. OpenCode 설정이 간결해지고 모델 전환도 덜 번거로워집니다.

전체 예시: Ollama 로컬 프로바이더

Ollama는 http://localhost:11434/v1에서 OpenAI 호환 로컬 엔드포인트를 제공합니다:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:30b": {
          "name": "Qwen3 Coder 30B"
        },
        "gemma4:e4b": {
          "name": "Gemma 4 E4B"
        }
      }
    }
  }
}

OpenCode를 시작하기 전에 모델을 미리 pull해 두세요:

ollama pull qwen3-coder:30b
ollama pull gemma4:e4b

OpenCode가 로컬 프로바이더에 인증을 요구하면 opencode auth login를 실행하고 Other를 선택한 다음, 프로바이더 ID로 ollama를 사용하고, ollama처럼 아무 값이나 입력하세요. Ollama는 로컬 API 키를 검증하지 않습니다.

일반적인 오류와 해결 방법

프로바이더가 /models에 표시되지 않음

네 가지를 확인하세요:

  1. opencode auth login 실행 시 입력한 프로바이더 ID가 설정 파일의 프로바이더 키와 일치하는지.
  2. 설정 파일이 유효한 JSON 또는 JSONC인지.
  3. 프로바이더 설정을 편집한 후 OpenCode를 재시작했는지.
  4. 모델이 프로바이더의 models 객체 안에 나열되어 있는지.

첫 요청에서 인증 실패

인증 정보가 없거나 잘못된 프로바이더 ID에 연결되어 있습니다. 다음을 실행하세요:

opencode auth list

프로바이더 ID가 설정과 정확히 일치하는지 확인하세요. 키 필드에 Bearer를 포함하지 마세요.

모델은 표시되지만 요청이 실패함

모델 ID가 업스트림 API가 기대하는 값과 다를 가능성이 높습니다. 커스텀 프로바이더는 모델 ID를 그대로 전달합니다. 설정에 qwen/qwen3-coder라고 되어 있으면, API도 정확히 qwen/qwen3-coder를 받아들여야 합니다.

Haimaker의 경우 키와 엔드포인트를 테스트해 보세요:

curl https://api.haimaker.ai/v1/models \
  -H "Authorization: Bearer your-haimaker-api-key"

Ollama의 경우 로컬 모델 목록을 확인하세요:

ollama list

출력에 표시된 정확한 모델 이름을 사용하세요.

로컬 모델에서 도구 호출 실패

로컬 모델은 컨텍스트 제한과 도구 호출 형식에 더 민감합니다. 에이전트 방식 코딩에 강하다고 알려진 모델(예: Qwen3 Coder)부터 시작하고, 컨텍스트 크기를 너무 크게 잡지 마세요. OpenCode 문서에서는 도구 호출이 작동하지 않을 때 Ollama의 num_ctx 값을 늘리는 것도 권장합니다.

내장 프로바이더가 작동하지 않음

의도치 않게 기존 설정을 덮어썼을 가능성이 높습니다. 커스텀 프로바이더는 provider 객체 아래에 추가하고, 기존 프로바이더 항목은 삭제하지 마세요. 확신이 없다면 최소한의 변경만 적용하세요. 프로바이더 ID 하나와 모델 하나를 추가하고, 재시작하고, 테스트한 다음 점진적으로 늘리세요.

실용적인 구성

대부분의 OpenCode 사용자에게 깔끔한 구성은 다음과 같습니다:

  1. Haimaker - 클라우드 모델과 키 하나로 라우팅하는 데 사용.
  2. Ollama - 로컬 개인 작업용.
  3. 프리미엄 폴백 하나 - 어려운 디버깅이나 멀티 파일 리팩토링용.

이렇게 하면 필요한 순간에는 로컬에서 비공개로 작업하고, 일상 작업에는 저비용 클라우드 모델을, 집중력이 많이 필요한 코딩 작업에는 더 강력한 모델을 활용할 수 있습니다.

OPENCODE에서 HAIMAKER 사용하기

로컬 설정은 OpenCode에서 Ollama 사용하기를 참조하세요. 더 넓은 로컬 모델 순위는 코딩 에이전트를 위한 최고의 Ollama 모델을 참조하세요.