GitHub Copilot App

1. 제품 소개

GitHub Copilot App은 GitHub의 데스크톱 코딩 Agent입니다. 로컬 프로젝트나 GitHub 저장소를 추가하고 자연어로 개발 작업을 수행할 수 있습니다. **BYOK(자체 모델 제공자 연결)**로 GravitexAI를 연결하면 GPT 또는 Claude 모델을 선택할 수 있습니다.

기능	설명
GUI 설정	Model providers에 주소, API 키, 모델을 입력하며 설정 파일 수정 불필요
여러 모델 사용	GPT와 Claude 제공자를 따로 등록하고 대화에서 선택
자율성 조절	Interactive, Plan, Autopilot 모드 지원
사용량 과금	자체 제공자 세션은 GravitexAI 계정으로 과금되며 Copilot 할당량을 소모하지 않음

GitHub Copilot App 1.1.x(2026년 10월) 기준입니다. BYOK는 Public Preview이므로 버전에 따라 문구가 달라질 수 있습니다. 영어 UI 이름을 기준으로 설명합니다.

2. 시스템 요구 사항

macOS 또는 Windows.
Git 설치.
GitHub 로그인 및 GravitexAI API 연결이 가능한 네트워크.

3. 사전 조건

클라이언트 로그인용 GitHub 계정.
GravitexAI 콘솔에서 생성한 API 키(sk-xxxxxxxxxx).

자체 모델 제공자만 사용한다면 GitHub Copilot 유료 구독은 필요하지 않습니다.

4. 빠른 시작

1단계: 클라이언트 설치

macOS
Windows

Homebrew로 설치합니다.

brew install --cask github-copilot-app

또는 프로세서에 맞는 패키지를 다운로드합니다.

DMG를 열고 GitHub Copilot을 응용 프로그램 폴더로 옮긴 뒤 실행합니다.

다른 버전은 GitHub Releases에서 확인하세요.

2단계: GitHub 로그인

Sign in to GitHub를 클릭하고 브라우저에서 인증합니다.

구독이 없는 경우: 시작 안내에서 continue with your own model provider를 선택하고 4단계의 값을 입력한 뒤 Save and continue를 누릅니다.
구독이 있는 경우: 메인 화면에 들어간 뒤 Settings에서 제공자를 추가합니다.

3단계: 모델 제공자 설정 열기

시스템	Settings 열기
macOS	GitHub Copilot → Settings 또는 `⌘ ,`
Windows	프로필/메뉴의 Settings 또는 `Ctrl + ,`

왼쪽 Model providers에서 Add provider를 클릭합니다.

4단계: GravitexAI 연결 정보 입력

필요한 GPT 또는 Claude 제공자를 추가합니다. 둘 다 사용하려면 두 제공자를 별도로 만드세요. 같은 GravitexAI API 키를 사용할 수 있습니다.

필드	GPT 제공자	Claude 제공자
제공자 유형	Any OpenAI-compatible HTTP endpoint	Anthropic
Display name	`Gravitex GPT`	`Gravitex Claude`
Base URL	`https://api.gravitex.ai/v1`	`https://api.gravitex.ai`
API key	GravitexAI API 키	같은 API 키
Wire API / API format(있는 경우)	Responses, `/v1/responses` 사용	별도 설정 없음, `/v1/messages` 사용

새 항목은 Add provider, 기존 항목 수정은 Save changes로 저장합니다.

GPT는 OpenAI 호환 유형, /v1이 포함된 주소와 Responses를 사용합니다. Claude는 Anthropic 유형과 /v1이 없는 주소를 사용합니다. Claude는 /v1/responses를 지원하지 않으므로 GPT 제공자에 넣지 마세요.

아래 예시의 표시 이름은 Anthropic입니다. Gravitex Claude로 바꾸면 모델 선택기에서 쉽게 구분할 수 있습니다. **Custom headers (JSON)**은 특별한 요구가 없다면 비워 둡니다.

5단계: 모델 추가

제공자 저장 후 카탈로그에서 모델을 선택하거나 ID를 직접 입력합니다.

제공자	모델 ID 예시
Gravitex GPT	`gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.3-codex`, `gpt-6-sol`
Gravitex Claude	`claude-opus-5-5`, `claude-sonnet-5-5`, `claude-haiku-5-5`, `claude-fable-5-1`

GravitexAI 모델 목록의 정확한 ID와 계정 사용 권한을 확인하세요. 카탈로그를 열기 전에 API 키를 저장해야 합니다.

6단계: 프로젝트와 모델 선택

Projects 옆의 **+**에서 프로젝트를 추가합니다.
옵션 대상
Local folder or repository 로컬 폴더 또는 저장소
GitHub repository GitHub 저장소
Repository URL 저장소 주소 입력
New session을 만듭니다.
입력창 아래 모델 선택기에서 Gravitex GPT 또는 Gravitex Claude 모델을 선택합니다. Reasoning effort가 있다면 작업에 맞게 조절합니다.
테스트 메시지를 보내 정상 응답을 확인합니다.

옵션	대상
Local folder or repository	로컬 폴더 또는 저장소
GitHub repository	GitHub 저장소
Repository URL	저장소 주소 입력

스크린샷은 기본 이름인 Anthropic을 사용합니다. 표시 이름을 변경했다면 모델 옆에 지정한 이름이 나타납니다.

5. 세션 모드

모드	동작
Interactive	기본값. 변경을 제안하고 확인 후 계속 진행
Plan	먼저 계획을 작성하고 검토 후 실행
Autopilot	코드 수정, 명령 실행, 테스트와 반복 작업을 자율 수행

Autopilot은 파일과 명령을 직접 실행합니다. Git으로 관리하는 프로젝트에서 사용하고 작업 후 변경 사항을 검토하세요.

6. 성공 확인

Model providers에 제공자가 저장되고 호환 모델이 하나 이상 추가되었습니다.
새 세션에서 해당 모델을 보고 선택할 수 있습니다.
invalid api key, endpoint_not_found, 모델 사용 불가 오류 없이 응답을 받습니다.

자체 제공자 사용량은 GravitexAI로 과금되며 Copilot 할당량을 소모하지 않습니다. 속도 제한이 발생해도 Copilot Auto 모델로 자동 전환되지 않습니다.

7. 문제 해결

Claude의 404 / endpoint_not_found

Anthropic과 https://api.gravitex.ai를 사용하고 /v1을 붙이지 마세요. /v1/v1/messages는 경로가 중복된 것입니다. Claude를 OpenAI 호환 Responses 제공자로 등록하지 마세요.

GPT의 404

Any OpenAI-compatible HTTP endpoint와 https://api.gravitex.ai/v1을 사용하세요. 형식 선택 옵션이 있다면 Responses를 고릅니다.

Invalid API key for this provider

Model providers에서 키 전체를 공백 없이 입력하고 저장하세요. 콘솔에서 유효한 키인지 확인합니다.

제공자에 /models 인터페이스가 없다는 오류

Provider doesn't expose a /models endpoint at this base URL이면 유형과 주소를 확인하세요. GPT는 https://api.gravitex.ai/v1, Claude는 https://api.gravitex.ai입니다. 계속 실패하면 모델 ID를 직접 입력합니다.

카탈로그에서 먼저 API 키를 추가하라는 메시지

Add an API key for this provider before browsing the catalog이면 제공자에 API 키를 입력하고 저장한 뒤 카탈로그를 여세요.

선택기에 GravitexAI 모델이 없음

제공자를 저장하고 모델을 선택하거나 직접 추가했는지 확인하세요. 표시 이름을 Anthropic으로 유지했다면 해당 그룹을 찾습니다. 필요하면 앱을 다시 시작하세요.

API 키는 어디에 저장되나요?

macOS 키체인 또는 Windows 자격 증명 관리자에 저장됩니다. 공개 스크린샷, 대화, 저장소에 키를 노출하지 마세요.

API 검증 명령(선택)

클라이언트 설정 후에도 호출되지 않으면 아래 요청으로 키와 인터페이스를 확인하세요. 자리표시자 키와 모델 ID를 실제 계정 값으로 바꿉니다.

curl https://api.gravitex.ai/v1/responses \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","input":"say OK"}'

curl https://api.gravitex.ai/v1/messages \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":20,"messages":[{"role":"user","content":"say OK"}]}'

Windows PowerShell에서는 curl.exe를 사용하고 줄 끝의 \를 백틱 `으로 바꾸세요.

대화형 AI

프로그래밍 개발

AI 에이전트

기술 엔지니어링

번역

1. 제품 소개

2. 시스템 요구 사항

3. 사전 조건

4. 빠른 시작

1단계: 클라이언트 설치

2단계: GitHub 로그인

3단계: 모델 제공자 설정 열기

4단계: GravitexAI 연결 정보 입력

5단계: 모델 추가

6단계: 프로젝트와 모델 선택

5. 세션 모드

6. 성공 확인

7. 문제 해결

API 검증 명령(선택)

8. 관련 자료

​1. 제품 소개

​2. 시스템 요구 사항

​3. 사전 조건

​4. 빠른 시작

​1단계: 클라이언트 설치

​2단계: GitHub 로그인

​3단계: 모델 제공자 설정 열기

​4단계: GravitexAI 연결 정보 입력

​5단계: 모델 추가

​6단계: 프로젝트와 모델 선택

​5. 세션 모드

​6. 성공 확인

​7. 문제 해결

​API 검증 명령(선택)

​8. 관련 자료

1. 제품 소개

2. 시스템 요구 사항

3. 사전 조건

4. 빠른 시작

1단계: 클라이언트 설치

2단계: GitHub 로그인

3단계: 모델 제공자 설정 열기

4단계: GravitexAI 연결 정보 입력

5단계: 모델 추가

6단계: 프로젝트와 모델 선택

5. 세션 모드

6. 성공 확인

7. 문제 해결

API 검증 명령(선택)

8. 관련 자료