GitHub Copilot에서 모든 OpenAI 호환 API를 사용하는 방법 — 커스텀 모델 설정 가이드

요약 (TL;DR) — 이제 GitHub Copilot을 통해 Chat (VS Code) 및 Copilot CLI를 모든 OpenAI 호환 엔드포인트(endpoint)로 연결할 수 있습니다. VS Code에서는 Chat: Manage Language Models를 실행하고, OpenAI Compatible 제공자를 선택한 뒤, Base URL과 키를 붙여넣으세요. Copilot CLI에서는 COPILOT_PROVIDER_BASE_URL, COPILOT_PROVIDER_API_KEY, 그리고 COPILOT_MODEL을 export 하세요. 인라인 완성(Inline completions)은 영향을 받지 않으며, 여전히 Copilot 자체 인프라에서 실행됩니다.

Copilot의 모델 메뉴에서 벗어나기 위해 Copilot을 떠날 필요는 없습니다. 20초 동안 환경 변수(env vars)를 설정하면 당신의 copilot CLI가 Claude Opus 4.6, GPT-5.4, 또는 로컬 vLLM 서버와 통신하게 됩니다. 비용은 Copilot 할당량이 아닌, 해당 제공자(provider)를 통해 청구됩니다.

Copilot에서 BYOK가 실제로 하는 역할

BYOK (Bring Your Own Key)를 사용하면 Chat 인터페이스와 에이전트 CLI가 GitHub의 호스팅된 모델 풀(model pool)을 거치지 않고, 사용자가 직접 인증한 모델을 사용할 수 있습니다. 연결 구조는 의도적으로 제한적입니다:

이러한 분리가 존재하는 이유는 자동 완성(completions) 기능에 임의의 엔드포인트가 보장할 수 없는 한 자릿수 밀리초(millisecond) 단위의 지연 시간(latency) 예산이 필요하기 때문입니다. Chat과 에이전트는 왕복 시간(round trip)을 허용하므로, 이들이 가장 먼저 개방되었습니다.

VS Code에서의 설정 방법

이 경로는 2025년 10월에 발표되었으며 이후 여러 제공자에 대해 안정 채널(stable channel)에 도입되었습니다 (GA는 2026년 4월 GitHub 변경 로그에서 확인되었습니다). 일반적인 OpenAI 호환 흐름은 다음과 같습니다:

1. 명령 팔레트(Command Palette)를 열고 → Chat: Manage Language Models를 선택합니다.
2. 제공자 목록에서 OpenAI Compatible을 선택합니다.
3. Base URL (/chat/completions를 제공해야 함), API key, 그리고 제공자가 노출하는 Model ID를 입력합니다.
4. Add Model을 누릅니다. 이제 모델이 Copilot Chat 모델 드롭다운 메뉴에 나타납니다.

알아두어야 할 두 가지 JSON 형식이 있습니다. settings.json에 있는 레거시(Legacy) github.copilot.chat.customOAIModels 객체는 안정화 버전(Stable releases)에서도 여전히 작동하지만, 사용 중단(Deprecated)으로 표시되어 있습니다:

"github.copilot.chat.customOAIModels": {
  "anthropic/claude-opus-4.6": {
    "name": "Claude Opus 4.6 (via ofox)",
...

이를 대체하는 방식(현재 Insiders 버전 전용)은 customendpoint 벤더를 사용하는 chatLanguageModels.json 워크스페이스 파일입니다. 이때 배열(Array) 형태와 OpenAI의 chat-completions, OpenAI의 responses, 그리고 Anthropic의 messages 프로토콜 중 하나를 선택하는 apiType 선택기에 유의하세요:

[
  {
    "name": "ofox.ai",
...

기능 플래그(toolCalling, vision)가 중요합니다. 만약 에이전트(Agent)가 모델이 도구(Tools)를 지원하지 않는다고 판단하면, 조용히 일반 채팅(Plain chat)으로 전환되어 사용자의 커스텀 명령이 전혀 실행되지 않을 수 있습니다.

Copilot CLI에서의 설정

CLI의 BYOK 문서가 가장 깔끔한 참조 자료입니다. copilot을 실행하기 전에 내보내야(Export) 하는 세 가지 환경 변수(Environment variables)는 다음과 같습니다:

export COPILOT_PROVIDER_BASE_URL=https://api.ofox.ai/v1
export COPILOT_PROVIDER_API_KEY=$OFOX_API_KEY
export COPILOT_MODEL=anthropic/claude-opus-4.6
...

로컬 Ollama 환경의 경우, 키를 완전히 제외해도 됩니다:

export COPILOT_PROVIDER_BASE_URL=http://localhost:11434
export COPILOT_MODEL=qwen2.5-coder:14b
copilot

CLI는 지정된 엔드포인트에 대해 OpenAI Chat Completions 프로토콜로 통신합니다. /v1/chat/completions가 해결(Resolve)되고 해당 엔드포인트에서 모델 ID(Model ID)가 유효하다면 정상적으로 작동합니다.

실제 예시: 엔드포인트로 ofox.ai 사용하기

ofox.ai는 Anthropic, Google, Alibaba 및 Moonshot 모델을 OpenAI Chat Completions 스키마(Schema) 뒤에서 노출하는 게이트웨이입니다. 세 가지 SDK를 번갈아 사용할 필요 없이 채팅 드롭다운에서 Claude나 Gemini를 사용할 수 있으므로 Copilot BYOK에 매우 유용합니다. 기본 URL(Base URL)은 https://api.ofox.ai/v1이며, 인증 헤더(Auth header)는 표준 Authorization: Bearer <key> 형식을 따릅니다.

Copilot에 노출하기 위해 설정된 전형적인 모델 ID 세트는 다음과 같습니다:

Copilot을 연결하기 전 스모크 테스트 (Smoke test):

curl https://api.ofox.ai/v1/chat/completions \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
...

만약 위 명령어가 choices[0].message.content를 반환한다면, Copilot이 정상적으로 연결될 것입니다. 만약 모델 ID에 대해 404 오류가 발생한다면, ID를 먼저 수정하십시오. Copilot은 이러한 오류를 실제 원인을 가리는 일반적인 "model unavailable" 토스트 메시지로 표시합니다. 일치하지 않는 ID 및 404 오류에 대한 심층적인 디버깅(Debugging)은 Model Not Found errors troubleshooting을 참조하십시오.

하나의 키로 여러 제공업체를 사용하는 게이트웨이 패턴 (Gateway pattern)에 대한 더 폭넓은 배경 지식은 OpenAI SDK migration guide 및 핵심 개요인 AI API aggregation: every model behind one endpoint를 참조하십시오.

실행 전 알아두어야 할 주의 사항

• 인증은 정적 자격 증명(Static credentials)만 지원합니다. BYOK는 API 키 또는 Bearer 토큰을 허용합니다. OAuth 핸드셰이크(handshake), 서비스 계정 흐름(service-account flow), 키 로테이션 훅(key rotation hook)은 지원되지 않습니다. 키를 다른 장기 비밀 정보(long-lived secret)와 동일하게 취급하십시오. 범위를 제한하고, 수동으로 로테이션하며, 공개 리포지토리(public repo)에 올리지 마십시오.
• 텔레메트리(Telemetry)는 여전히 GitHub로 전송됩니다. BYOK는 추론(inference)이 발생하는 위치를 변경할 뿐, 사용 텔레메트리가 전송되는 위치를 변경하지는 않습니다. 컴플라이언스(compliance) 이유로 모델 마이그레이션이 필요했던 엔터프라이즈 관리자는 BYOK만으로 충분하다고 가정하기 전에 데이터 처리 문서를 다시 읽어보아야 합니다.
• 속도 제한(Rate limits)은 직접 관리해야 합니다. Copilot의 할당량(quota)이 더 이상 보호해 주지 않습니다. 제공업체가 속도 제한을 걸면 채팅 패널이 중단될 뿐입니다. 첫 일주일 동안은 제공업체의 대시보드를 주시하십시오.
• 코드 완성(Code completions)은 여전히 Copilot에서 작동합니다. 가장 흔한 오해이기에 다시 강조합니다: BYOK는 인라인 고스트 텍스트(inline ghost-text) 완성 기능을 대체하지 않습니다. 해당 기능은 여전히 GitHub가 호스팅하는 모델을 사용합니다.

IDE 커스텀 API 옵션 비교

Copilot BYOK와 다른 에디터의 유사한 기능 사이에서 고민 중이라면, 겉보기에는 비슷해 보일 수 있으나 에이전트(agent) 역량은 다릅니다. Cursor / Claude Code / Cline 커스텀 API 설정 가이드에서 이 세 가지에 대한 동일한 과정을 설명하고 있습니다. 요약하자면: Copilot의 BYOK는 에디터 내 흐름이 가장 깔끔하며(UI 양식 형태), Claude Code는 ANTHROPIC_BASE_URL과 결합했을 때 달러당 가장 강력한 에이전트 성능을 제공하며, Cursor는 그 중간 단계에 위치합니다.

문제 해결 (Troubleshooting)

"Failed to fetch model list" — Base URL에 /v1이 누락되었거나, 엔드포인트가 GET /models 경로를 제공하지 않는 경우입니다. OpenAI 호환(OpenAI-Compatible) 제공업체는 드롭다운 목록을 채우기 위해 /models를 탐색합니다. 게이트웨이에서 이를 노출하지 않는 경우, 양식에 모델 ID를 수동으로 입력하십시오.

첫 번째 턴 이후 채팅이 멈춤 — Copilot에서 도구 호출 (Tool calling) 기능이 활성화되어 있지만, 모델이 예상되는 tool_calls 페이로드 형식을 반환하지 않는 경우입니다. customOAIModels 항목에서 toolCalling: false로 설정을 변경하거나, OpenAI 도구 사양 (tools spec)을 완전히 구현하는 모델로 전환하십시오.

**CLI에서