OpenCode

OpenCode는 터미널에서 실행되는 오픈 소스 AI 코딩 도구입니다. CC Switch 가져오기 또는 설정 파일 직접 편집으로 HiAPI에 연결할 수 있으며, 둘 중 하나를 선택하세요. 아래 단계는 deepseek-v4.1-flash를 예로 사용하며, HiAPI는 OpenAI Chat Completions 프로토콜을 사용합니다. 이 튜토리얼은 Windows 11에서 OpenCode 1.19.4로 검증했습니다. 시작하기 전에 HiAPI API 키를 준비하세요. CC Switch로 가져오려면 먼저 CC Switch 설치 및 원클릭 가져오기에 설명된 대로 OpenCode를 지원하는 버전을 설치하세요.

1. OpenCode 설치

Mac / Linux에서는 터미널에서 실행하세요:

curl -fsSL https://opencode.ai/install | bash

이미 Node.js가 있다면(Node.js 설치 참고) npm으로도 설치할 수 있습니다. Windows에서는 WSL 안에서 위 설치 스크립트를 사용하거나, 로컬 터미널에서 실행하세요:

npm install -g opencode-ai

설치한 뒤 터미널을 다시 열고 버전을 확인하세요:

opencode --version

버전 번호가 보이면 충분합니다.

2. HiAPI 설정

방법 1: CC Switch로 원클릭 가져오기

1. HiAPI OpenCode 연결 페이지를 열고 모델과 HiAPI API 키를 선택한 뒤 Prepare import를 클릭합니다.

2. CC Switch의 “Confirm provider import” 창에서 아래 항목을 확인한 뒤 Import를 클릭합니다:

방법 2: 설정 파일 직접 편집

전역 설정 파일 ~/.config/opencode/opencode.json을 열고 HiAPI 공급자(OpenAI Chat Completions 프로토콜)를 추가하세요. 파일이 없으면 새로 만들고, 이미 다른 설정이 있다면 아래의 provider.hiapi와 model 필드만 병합하세요. Base URL은 /chat/completions를 덧붙이지 않고 https://api.hiapi.ai/v1로 설정합니다.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "hiapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "HiAPI",
      "options": {
        "baseURL": "https://api.hiapi.ai/v1",
        "apiKey": "{env:HIAPI_API_KEY}"
      },
      "models": {
        "deepseek-v4.1-flash": {
          "name": "DeepSeek V4.1 Flash"
        },
        "claude-opus-5-5": {
          "name": "Claude Opus 5.5"
        }
      }
    }
  },
  "model": "hiapi/deepseek-v4.1-flash"
}

{env:HIAPI_API_KEY}는 OpenCode가 환경 변수를 읽는 방식이므로 그대로 두세요. 그런 다음 터미널에서 해당 변수를 설정하세요. YOUR_HIAPI_API_KEY를 자신의 HiAPI API 키로 바꾸고 따옴표는 유지합니다:

export HIAPI_API_KEY="YOUR_HIAPI_API_KEY"

$env:HIAPI_API_KEY = "YOUR_HIAPI_API_KEY"

환경 변수는 현재 터미널에만 적용되므로 설정한 같은 터미널에서 OpenCode를 시작하세요. 터미널을 다시 열면 다시 설정하거나, 셸 시작 파일(예: ~/.zshrc)에 추가해 영구 적용하세요.

예시는 hiapi/deepseek-v4.1-flash를 기본 모델로 설정합니다. 모델을 바꾸려면 provider.hiapi.models 아래의 모델 정의와 model 필드를 모두 변경하세요.

3. 확인

환경 변수를 설정한 터미널에서 프로젝트 디렉터리로 이동해 OpenCode를 시작하세요:

opencode

/models를 입력하고 HiAPI 공급자 아래의 모델(예: deepseek-v4.1-flash)을 선택하세요. “안녕하세요, 한 문장으로 자기소개를 해 주세요.”를 보내세요. 정상적으로 답하면 연결이 된 것입니다.

가져오기 방법에 따라 공급자 이름이 다를 수 있습니다. 현재 선택된 공급자, 모델 이름, Base URL만 확인하면 됩니다. HiAPI 콘솔의 요청 로그에서 요청이 HiAPI를 거쳐 가는지도 확인할 수 있습니다.

4. 문제 해결

여기에는 OpenCode에 특화된 문제만 정리했습니다. 401, 404, 429 같은 일반적인 오류는 자주 발생하는 오류를 참고하세요.