> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode에서 AiHubMix 사용하기

OpenCode는 이제 새로운 모델 제공자로 AiHubMix를 지원합니다. OpenCode 내에서 AiHubMix API 키를 사용하여 해당 모델 서비스에 액세스할 수 있습니다.

AiHubMix는 현재 GPT, Claude, DeepSeek, Gemini, Qwen을 포함한 주요 모델 패밀리를 지원합니다. OpenCode에서 최적의 성능을 위해 다음 모델이 권장됩니다:

* `claude-sonnet-4-5`
* `glm-4.6`
* `gpt-5`
* `gpt-5-codex`

이 가이드는 다양한 운영 체제에서 OpenCode를 설치, 구성 및 실행하고 AiHubMix API에 연결하는 단계별 지침을 제공합니다.

***

## 시스템 요구사항

설치 전에 시스템이 다음 요구사항을 충족하는지 확인하세요:

* Node.js ≥ 18.0.0
* 패키지 매니저(OS에 따라 선택사항):
  * macOS / Linux: `brew`
  * Arch Linux: `paru`
  * Windows: `choco`, `winget`, 또는 `scoop`

***

1. OpenCode 설치

다음 방법 중 하나를 사용하여 OpenCode를 설치할 수 있습니다:

**Node.js 사용**

```
# CURL 사용 
curl -fsSL https://opencode.ai/install | bash

# NPM 사용
npm install -g opencode-ai

# Bun 사용
bun install -g opencode-ai

# PNPM 사용
pnpm install -g opencode-ai

# Yarn 사용
yarn global add opencode-ai
```

***

**Homebrew 사용 (macOS / Linux)**

```
brew install sst/tap/opencode
```

***

**Paru 사용 (Arch Linux)**

```
paru -S opencode-bin
```

***

**Windows에서**

```
# Chocolatey 사용
choco install opencode

# WinGet 사용
winget install opencode

# Scoop 사용
scoop bucket add extras
scoop install extras/opencode

# NPM 사용 (Node.js 및 관리자 권한 필요)
npm install -g opencode-ai
```

***

2. OpenCode 실행 및 로그인

설치 후 다음 단계에 따라 로그인하고 OpenCode를 구성하세요.

### 단계 1. 로그인

터미널에서 다음 명령을 실행하세요:

```
opencode auth login
```

***

### 단계 2. AI 제공자 선택

로그인 인터페이스에서 모델 제공자로 AiHubMix를 선택하세요.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/aihubmix/public/en/oc1.png" alt="그림" />

***

### 단계 3. API 키로 인증

AiHubMix 계정에 로그인하여 API 키를 획득하세요. OpenCode 로그인 화면에서 입력하여 인증을 완료하세요.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/aihubmix/public/en/oc2.png" alt="그림" />

<img src="https://mintlify.s3.us-west-1.amazonaws.com/aihubmix/public/en/oc3.png" alt="그림" />

***

3. 설치 확인

OpenCode가 성공적으로 설치되고 구성되었는지 확인하려면 다음을 실행하세요:

```
opencode
```

<img src="https://mintlify.s3.us-west-1.amazonaws.com/aihubmix/public/en/oc4.png" alt="그림" />

콘솔이 유효한 모델 응답을 반환하면 설정이 완료된 것입니다.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/aihubmix/public/en/oc5.png" alt="그림" />

***

<h2 id="custom-base-url">
  사용자 지정 Base URL
</h2>

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

#### 1단계: 설정 파일 열기

`~/.config/opencode/opencode.json`(Windows에서는 `%USERPROFILE%\.config\opencode\opencode.json`)을 엽니다.

#### 2단계: `options.baseURL` 추가

`aihubmix` provider 아래에 `options.baseURL`을 추가합니다. 이 필드 하나만 작성하면 OpenCode가 내장 설정과 자동으로 깊은 병합(deep merge)을 수행하므로, provider 전체를 다시 작성할 필요가 없습니다:

```json theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "aihubmix": {
      "options": {
        "baseURL": "https://api.inferera.com"
      }
    }
  }
}
```

> **참고**: `baseURL`은 도메인 수준(예: `https://api.inferera.com`)까지만 입력하면 됩니다. `/v1` 등의 경로는 SDK가 자동으로 이어 붙입니다. 직접 `/v1`을 추가하지 마세요(예: `https://api.inferera.com/v1`). 그렇게 하면 `/v1/v1/`로 이어져 404가 발생합니다.

#### 3단계: 재시작 및 확인

OpenCode를 완전히 종료한 후 다시 시작합니다. 다음 명령을 실행하여 확인하세요:

```bash theme={null}
opencode debug config
```

출력된 `provider.aihubmix.options.baseURL`에서 입력한 주소를 확인할 수 있어야 합니다.

***

4. 문제 및 팁

* API 키 검증이 실패하면 AiHubMix에서 재인증하고 키의 상태를 확인하세요.
* 앱 내 도움말 보기: `opencode` -> `/help`
* 공식 문서: [https://opencode.ai/docs/](https://opencode.ai/docs/)

***

마지막 업데이트: 2026-06-01