Skip to main content
OpenCode는 현재 GPT, Claude, DeepSeek, Gemini, Qwen 등 주요 모델 패밀리를 지원합니다. OpenCode 사용 환경에서는 다음 모델을 권장합니다:
  • coding-minimax-m2.1-free
  • coding-glm-4.7-free
  • claude-sonnet-4-5
  • gpt-5
  • gpt-5-codex
이 문서에서는 다양한 운영 체제에서 OpenCode를 설치, 설정, 실행하고 AIHubMix API에 연결하는 방법을 설명합니다.
설치를 시작하기 전에 시스템이 다음 요구 사항을 충족하는지 확인하세요:
  • Node.js ≥ 18.0.0
  • 운영 체제별 패키지 관리자(선택 사항):
    • macOS / Linux: brew
    • Arch Linux: paru
    • Windows: choco, winget 또는 scoop

1. OpenCode 설치

사용 중인 시스템과 도구에 따라 아래 설치 방법 중 하나를 선택하세요.

1. Node.js로 설치

2. Homebrew로 설치(macOS / Linux)

3. Paru로 설치(Arch Linux)

4. Windows에서 설치

2. OpenCode 실행 및 로그인

설치가 완료되면 아래 단계에 따라 로그인과 설정을 진행합니다.

1. OpenCode에 로그인

터미널에서 다음 명령을 실행합니다:

2. 모델 제공자 선택

로그인 화면에서 모델 제공자로 AiHubMix를 선택합니다. Opencode 1

3. API 키 인증

AiHubMix API 키를 OpenCode 로그인 화면에 입력하여 인증을 완료합니다. Opencode 2

3. 모델 사용

1. 설치 확인

다음 명령으로 OpenCode가 정상적으로 설치 및 설정되었는지 확인할 수 있습니다:
Opencode 3

2. 모델 선택

/models를 입력하고 aihubmix를 검색한 뒤 원하는 모델을 선택합니다. Opencode 4

4. OpenCode 데스크톱 클라이언트에서 AiHubMix 사용하기

  1. OpenCode 데스크톱 앱을 내려받습니다: https://opencode.ai/download .
  2. OpenCode를 열고 /modelConnect provideraihubmix 검색 → API 키 입력 → Submit 순서로 진행합니다. Opencode 5
  3. 모델 선택 창에서 aihubmix를 검색하고 사용할 모델을 선택하면 됩니다. Opencode 6

5. 모델 수동 설정 및 업데이트

DeepSeek V4 Pro를 추가하는 경우를 예로 들어 설명합니다.

1단계: 모델 ID 확인

AIHubMix 모델 화면에서 대상 모델을 찾아 ID를 복사합니다. API로 직접 조회할 수도 있습니다:

2단계: 설정 파일 열기

사용 중인 시스템에 맞는 명령을 터미널에서 실행합니다: Mac
Linux
Windows(PowerShell에서 실행)
파일을 열면 빈 파일이거나 기존 JSON 내용이 표시됩니다.

3단계: 설정 작성

빈 파일인 경우 아래 내용을 그대로 붙여 넣습니다:
이미 내용이 있는 경우 "models" 안에 새 모델을 추가하고 모델 사이를 쉼표로 구분합니다:
참고: 마지막 모델 뒤에는 쉼표를 넣지 마세요. 파일 형식이 잘못됩니다.
파일 저장: Mac은 Command + S, Windows는 Ctrl + S. 필드 설명:

4단계: OpenCode 재시작

설정 파일을 저장한 뒤 OpenCode를 완전히 종료하고 다시 실행해야 새 모델이 로드됩니다.

5단계: 확인

모델 선택 창(기본 단축키 ;)을 열고 V4 또는 DeepSeek을 검색하여 DeepSeek-V4-Pro가 목록에 나타나는지 확인합니다.

  1. 사용자 지정 Base URL

기본적으로 OpenCode는 AiHubMix 요청을 https://aihubmix.com/v1로 전송합니다. 요청을 자체 구축한 게이트웨이, 기업 프록시 또는 가속 노드로 보내야 하는 경우, OpenCode 소스 코드를 수정하거나 재설치할 필요 없이 options.baseURL을 통해 재정의할 수 있습니다.

1단계: 설정 파일 열기

「5. 모델 수동 설정 및 업데이트」와 같은 방법으로 ~/.config/opencode/opencode.json(Windows에서는 %USERPROFILE%\.config\opencode\opencode.json)을 엽니다.

2단계: options.baseURL 추가

aihubmix provider 아래에 options.baseURL을 추가합니다. 이 필드 하나만 작성하면 OpenCode가 내장 설정과 자동으로 깊은 병합(deep merge)을 수행하므로, provider 전체를 다시 작성할 필요가 없습니다:
참고: baseURL은 도메인 수준(예: https://api.inferera.com)까지만 입력하면 됩니다. /v1, /chat/completions 등의 경로는 SDK가 자동으로 이어 붙입니다. 직접 /v1을 추가하지 마세요(예: https://api.inferera.com/v1). 그렇게 하면 /v1/v1/로 이어져 404가 발생합니다.

3단계: 재시작 및 확인

OpenCode를 완전히 종료한 후 다시 시작합니다. 다음 명령을 실행하여 설정이 적용되었는지 확인할 수 있습니다:
출력된 provider.aihubmix.options.baseURL에서 입력한 주소를 확인할 수 있어야 하며, 이후 모든 모델 요청이 해당 주소로 전송됩니다. 필드 설명:

7. 자주 묻는 질문과 팁

  • API 키 검증이 실패하면 AIHubMix에 다시 로그인하여 키가 유효한지 확인하세요.
  • 앱 내 도움말 보기: opencode/help
  • OpenCode 공식 문서: https://opencode.ai/docs/

마지막 업데이트: 2026-07-29