3단계 OpenCode API 중계소 연동 설정, 400+ AI 모델 자유 전환 잠금 해제

오픈소스 AI 코딩 어시스턴트인 OpenCode를 사용하고 싶지만, 공식 API 가격이 너무 비싸거나 네트워크가 불안정해서 고민이신가요? API 중계 서버(API Relay)가 최적의 해결책입니다. 본 포스팅에서는 APIYI, OpenRouter와 같은 중계 서비스를 OpenCode에 연결하는 방법 3단계를 차근차근 알려드릴게요. Claude, GPT-4, Gemini 등 75개 이상의 주요 대규모 언어 모델을 훨씬 저렴한 비용으로 이용할 수 있습니다.

핵심 가치: 이 글을 읽고 나면 OpenCode에서 OpenAI와 호환되는 모든 API를 설정하여, 모델을 자유롭게 전환하고 비용을 최적화하는 방법을 배우게 됩니다.

OpenCode란 무엇인가요? 왜 API 중계 서버를 연결해야 할까요?

OpenCode는 Claude Code의 오픈소스 대체제로 불리는 터미널 기반 AI 코딩 어시스턴트입니다. Go 언어로 개발되었으며 미려한 TUI 인터페이스, 멀티 세션 관리, LSP 통합 등 전문적인 기능을 제공하죠.

OpenCode 핵심 기능 일람

왜 API 중계 서버를 사용해야 할까요?

공식 API를 직접 사용하는 경우 다음과 같은 문제에 직면할 수 있습니다.

🚀 빠른 시작: 바로 사용할 수 있는 OpenAI 호환 인터페이스를 제공하는 APIYI(apiyi.com)를 중계 서버로 추천합니다. 가입 즉시 무료 테스트 크레딧을 받을 수 있으며, 5분 안에 OpenCode 설정을 마칠 수 있어요.

OpenCode API 프록시 연결 핵심 요약

설정을 시작하기 전, OpenCode의 API 연결 원리를 먼저 가볍게 살펴볼까요?

설정 아키텍처 설명

OpenCode는 통합 설정 관리 체계를 채택하여 다층적인 설정 덮어쓰기를 지원합니다.

API 프록시 연결 원리

OpenCode는 @ai-sdk/openai-compatible 어댑터를 통해 모든 OpenAI 호환 API를 지원합니다. 주요 설정 항목은 다음과 같습니다.

• baseURL: API 프록시 스테이션의 인터페이스 주소
• apiKey: 프록시 업체에서 제공하는 API 키
• models: 사용 가능한 모델 리스트

즉, 프록시 업체에서 표준 /v1/chat/completions 인터페이스만 제공한다면 바로 OpenCode에 연결해 사용할 수 있습니다.

OpenCode 빠른 시작 가이드

1단계: OpenCode 설치하기

OpenCode는 다양한 설치 방식을 지원합니다. 가장 편한 방법을 선택해 보세요.

한 줄 설치 스크립트 (권장):

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

Homebrew 설치 (macOS/Linux):

brew install opencode-ai/tap/opencode

npm 설치:

npm i -g opencode-ai@latest

Go 설치:

go install github.com/opencode-ai/opencode@latest

설치가 잘 되었는지 확인해 볼까요?

opencode --version

2단계: API 프록시 키 설정하기

OpenCode는 두 가지 인증 방식을 지원합니다.

방법 1: /connect 명령 사용 (권장)

OpenCode를 실행한 후, /connect 명령을 입력하세요.

opencode
# TUI 화면에서 입력
/connect

Other를 선택해 커스텀 Provider를 추가하고 API 키를 입력합니다. 키는 ~/.local/share/opencode/auth.json에 안전하게 저장됩니다.

방법 2: 환경 변수 설정

~/.zshrc 또는 ~/.bashrc 파일에 다음 내용을 추가하세요.

# APIYI 프록시 설정
export OPENAI_API_KEY="sk-your-apiyi-key"
export OPENAI_BASE_URL="https://api.apiyi.com/v1"

설정을 적용합니다.

source ~/.zshrc

3단계: opencode.json 설정 파일 생성하기

가장 중요한 단계입니다! 설정을 통해 API 프록시 스테이션을 지정해 줍니다.

글로벌 설정 (모든 프로젝트에 적용):

mkdir -p ~/.config/opencode
touch ~/.config/opencode/opencode.json

프로젝트 설정 (현재 프로젝트에만 적용):

touch opencode.json  # 프로젝트 루트 디렉토리

최소 설정 예시

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "apiyi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "APIYI",
      "options": {
        "baseURL": "https://api.apiyi.com/v1",
        "apiKey": "{env:OPENAI_API_KEY}"
      },
      "models": {
        "claude-sonnet-4-20250514": {
          "name": "Claude Sonnet 4"
        },
        "gpt-4o": {
          "name": "GPT-4o"
        }
      }
    }
  },
  "model": "apiyi/claude-sonnet-4-20250514"
}

설정 팁: {env:OPENAI_API_KEY} 문법을 사용하면 환경 변수에서 키를 자동으로 읽어옵니다. 설정 파일에 직접 키를 적지 않아도 되어 안전하죠. APIYI(apiyi.com)에서 발급받은 API Key는 OpenAI 포맷과 호환되므로 바로 사용 가능합니다.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "apiyi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "APIYI (권장)",
      "options": {
        "baseURL": "https://api.apiyi.com/v1",
        "apiKey": "{env:APIYI_API_KEY}"
      },
      "models": {
        "claude-sonnet-4-20250514": {
          "name": "Claude Sonnet 4",
          "limit": {
            "context": 200000,
            "output": 65536
          }
        },
        "claude-opus-4-20250514": {
          "name": "Claude Opus 4",
          "limit": {
            "context": 200000,
            "output": 32000
          }
        },
        "gpt-4o": {
          "name": "GPT-4o",
          "limit": {
            "context": 128000,
            "output": 16384
          }
        },
        "gpt-4o-mini": {
          "name": "GPT-4o Mini",
          "limit": {
            "context": 128000,
            "output": 16384
          }
        },
        "gemini-2.5-pro": {
          "name": "Gemini 2.5 Pro",
          "limit": {
            "context": 1000000,
            "output": 65536
          }
        },
        "deepseek-chat": {
          "name": "DeepSeek V3",
          "limit": {
            "context": 64000,
            "output": 8192
          }
        }
      }
    },
    "openrouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OpenRouter",
      "options": {
        "baseURL": "https://openrouter.ai/api/v1",
        "apiKey": "{env:OPENROUTER_API_KEY}",
        "headers": {
          "HTTP-Referer": "https://your-site.com",
          "X-Title": "OpenCode Client"
        }
      },
      "models": {
        "anthropic/claude-sonnet-4": {
          "name": "Claude Sonnet 4 (OpenRouter)"
        },
        "openai/gpt-4o": {
          "name": "GPT-4o (OpenRouter)"
        }
      }
    }
  },
  "model": "apiyi/claude-sonnet-4-20250514",
  "small_model": "apiyi/gpt-4o-mini",
  "agent": {
    "coder": {
      "model": "apiyi/claude-sonnet-4-20250514",
      "maxTokens": 8000
    },
    "planner": {
      "model": "apiyi/gpt-4o",
      "maxTokens": 4000
    }
  },
  "tools": {
    "write": true,
    "bash": true,
    "glob": true,
    "grep": true
  }
}

OpenCode 지원 API 중계 사이트 비교

주요 API 중계 사이트 설정 파라미터

APIYI 설정 상세 안내

APIYI는 개발자를 위해 최적화된 AI API 중계 플랫폼으로, 다음과 같은 기능을 제공해요:

• 통합된 OpenAI 호환 인터페이스
• Claude, GPT, Gemini, DeepSeek 등 주요 모델 지원
• 사용량 기반 과금, 월회비 없음
• 무료 테스트 크레딧 제공
• 빠른 고객 지원 서비스

{
  "provider": {
    "apiyi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "APIYI",
      "options": {
        "baseURL": "https://api.apiyi.com/v1"
      },
      "models": {
        "claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" },
        "claude-opus-4-20250514": { "name": "Claude Opus 4" },
        "gpt-4o": { "name": "GPT-4o" },
        "gpt-4o-mini": { "name": "GPT-4o Mini" },
        "gemini-2.5-pro": { "name": "Gemini 2.5 Pro" },
        "deepseek-chat": { "name": "DeepSeek V3" }
      }
    }
  }
}

OpenRouter 설정 상세 안내

OpenRouter는 400개 이상의 대규모 언어 모델을 통합 제공하며, 모델을 자주 교체해야 하는 상황에 적합해요:

{
  "provider": {
    "openrouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OpenRouter",
      "options": {
        "baseURL": "https://openrouter.ai/api/v1",
        "apiKey": "{env:OPENROUTER_API_KEY}",
        "headers": {
          "HTTP-Referer": "https://your-app.com",
          "X-Title": "My OpenCode App"
        }
      },
      "models": {
        "anthropic/claude-sonnet-4": {
          "name": "Claude Sonnet 4"
        },
        "google/gemini-2.5-pro": {
          "name": "Gemini 2.5 Pro"
        },
        "meta-llama/llama-3.1-405b": {
          "name": "Llama 3.1 405B"
        }
      }
    }
  }
}

💡 선택 가이드: 주로 Claude나 GPT 시리즈 모델을 사용하신다면, 가격이 더 저렴하고 응답 속도가 빠른 APIYI(apiyi.com)를 추천드려요. 오픈 소스 모델이나 비주류 모델이 필요하다면 OpenRouter가 더 넓은 범위를 지원합니다.

OpenCode 고급 설정 팁

Agent 모델 할당 전략

OpenCode에는 Coder와 Planner라는 두 개의 Agent가 내장되어 있으며, 각각의 역할에 맞춰 서로 다른 모델을 할당할 수 있습니다.

{
  "agent": {
    "coder": {
      "model": "apiyi/claude-sonnet-4-20250514",
      "maxTokens": 8000,
      "description": "주요 코딩 작업, 강력한 모델 사용"
    },
    "planner": {
      "model": "apiyi/gpt-4o-mini",
      "maxTokens": 4000,
      "description": "기획 및 분석, 비용 절감을 위한 경량 모델 사용"
    }
  }
}

다중 Provider 전환

여러 개의 Provider를 설정한 후에는 OpenCode 내에서 /models 명령어를 사용하여 언제든지 모델을 전환할 수 있습니다.

# OpenCode 실행
opencode

# TUI에서 모델 전환
/models
# apiyi/claude-sonnet-4-20250514 또는 다른 모델 선택

환경 변수 베스트 프랙티스

API 키는 .env 파일에서 관리하는 것이 보안상 좋습니다.

# .env 파일
APIYI_API_KEY=sk-your-apiyi-key
OPENROUTER_API_KEY=sk-or-your-openrouter-key

그 다음 opencode.json에서 해당 변수를 참조하도록 설정합니다.

{
  "provider": {
    "apiyi": {
      "options": {
        "apiKey": "{env:APIYI_API_KEY}"
      }
    }
  }
}

Token 제한 설정

모델의 컨텍스트 및 출력 제한을 지정하여 토큰 초과 오류를 방지하세요.

{
  "models": {
    "claude-sonnet-4-20250514": {
      "name": "Claude Sonnet 4",
      "limit": {
        "context": 200000,
        "output": 65536
      }
    }
  }
}

OpenCode 자주 묻는 질문(FAQ) 및 문제 해결

설정 과정에서 발생할 수 있는 문제와 해결 방법입니다.

"baseURL": "https://api.apiyi.com/v1"

"baseURL": "https://api.apiyi.com/v1/chat/completions"

{
  "provider": {
    "apiyi": {
      "models": {
        "claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" }
      }
    }
  },
  "model": "apiyi/claude-sonnet-4-20250514"
}

# 설정된 인증 정보 확인
opencode auth list

# 사용 가능한 모델 확인
opencode
/models

# 간단한 대화 테스트
opencode -p "안녕하세요, 한국어로 대답해 주세요"

opencode
/models
# 다른 Provider 아래에 있는 모델을 선택하면 바로 전환됩니다.

{
  "model": "apiyi/claude-sonnet-4-20250514"
}

OpenCode vs Claude Code: API 연동 방식 비교

🎯 기술 제안: OpenCode의 가장 큰 장점은 모델 유연성에 있어요. APIYI(apiyi.com) 중계 플랫폼을 활용하면, 같은 설정으로 Claude, GPT-4, Gemini 등 여러 대규모 언어 모델을 간편하게 갈아타며 나에게 딱 맞는 가성비 조합을 찾을 수 있답니다.

참고 자료

OpenCode를 설정할 때 유용한 참고 자료들입니다:

요약

이 글에서 소개한 3단계 설정 방법을 통해 여러분은 다음 내용을 완벽히 익히셨을 거예요:

1. OpenCode 설치: 원클릭 스크립트나 패키지 관리자를 사용하여 빠르게 설치하는 법
2. API 키 설정: /connect 명령어 또는 환경 변수를 통해 인증을 설정하는 법
3. 설정 파일 생성: opencode.json 파일을 작성하여 API 중계 서버와 모델을 지정하는 법

OpenCode는 오픈 소스 기반의 터미널 AI 프로그래밍 어시스턴트입니다. API 중계 서비스와 함께 활용하면 비용을 효과적으로 제어하고 모델 선택의 유연성을 유지하면서도, Claude Code에 버금가는 강력한 성능을 경험할 수 있습니다.

지금 바로 APIYI(apiyi.com)에서 API 키를 발급받아 테스트를 시작해 보세요. 플랫폼에서 무료 크레딧을 제공할 뿐만 아니라 Claude, GPT, Gemini 등 주요 대규모 언어 모델을 모두 지원하며, 통일된 인터페이스 규격 덕분에 설정 과정이 훨씬 간단해집니다.

📝 작성자: APIYI 기술 팀 | APIYI apiyi.com – AI API 호출을 더 간편하게