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

# GitHub Copilot App

> GitHub Copilot 데스크톱 클라이언트에서 GravitexAI GPT 및 Claude 모델을 사용하는 가이드

## 1. 제품 소개

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

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

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

## 2. 시스템 요구 사항

* macOS 또는 Windows.
* [Git](https://git-scm.com/) 설치.
* GitHub 로그인 및 GravitexAI API 연결이 가능한 네트워크.

## 3. 사전 조건

* 클라이언트 로그인용 GitHub 계정.
* [GravitexAI 콘솔](https://maas.gravitex.ai/#/api-keys)에서 생성한 API 키(`sk-xxxxxxxxxx`).

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

## 4. 빠른 시작

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

> [tab] macOS
>
> Homebrew로 설치합니다.
>
> ```bash theme={null}
> brew install --cask github-copilot-app
> ```
>
> 또는 프로세서에 맞는 패키지를 다운로드합니다.
>
> * [Apple Silicon](https://github.com/github/app/releases/latest/download/GitHub-Copilot-darwin-arm64.dmg)
> * [Intel](https://github.com/github/app/releases/latest/download/GitHub-Copilot-darwin-x64.dmg)
>
> DMG를 열고 GitHub Copilot을 응용 프로그램 폴더로 옮긴 뒤 실행합니다.

> [tab] Windows
>
> 시스템에 맞는 설치 프로그램을 다운로드해 실행합니다.
>
> * [Windows x64](https://github.com/github/app/releases/latest/download/GitHub-Copilot-windows-x64-setup.exe)
> * [Windows ARM64](https://github.com/github/app/releases/latest/download/GitHub-Copilot-windows-arm64-setup.exe)

다른 버전은 [GitHub Releases](https://github.com/github/app/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**를 클릭합니다.

![Model providers에서 Add provider 선택](https://mintcdn.com/gravitexai/QXITE-rsvJBzaoaP/images/github-copilot-app-1.png?fit=max\&auto=format\&n=QXITE-rsvJBzaoaP\&q=85\&s=22a7af4e2a7f430c5055ab78be1e12e9)

### 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**로 저장합니다.

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

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

![Base URL에 /v1을 넣지 않는 Anthropic 설정](https://mintcdn.com/gravitexai/QXITE-rsvJBzaoaP/images/github-copilot-app-2.png?fit=max\&auto=format\&n=QXITE-rsvJBzaoaP\&q=85\&s=1f7b5a0498201a44f3e79152a642818a)

### 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` |

> [!TIP]
>
> [GravitexAI 모델 목록](https://maas.gravitex.ai/#/api-models)의 정확한 ID와 계정 사용 권한을 확인하세요. 카탈로그를 열기 전에 API 키를 저장해야 합니다.

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

1. **Projects** 옆의 \*\*+\*\*에서 프로젝트를 추가합니다.

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

2. **New session**을 만듭니다.

3. 입력창 아래 모델 선택기에서 **Gravitex GPT** 또는 **Gravitex Claude** 모델을 선택합니다. **Reasoning effort**가 있다면 작업에 맞게 조절합니다.

4. 테스트 메시지를 보내 정상 응답을 확인합니다.

![대화에서 설정한 Claude 모델 선택](https://mintcdn.com/gravitexai/QXITE-rsvJBzaoaP/images/github-copilot-app-3.png?fit=max\&auto=format\&n=QXITE-rsvJBzaoaP\&q=85\&s=b7ac69928e0ba21e80c44cd5887debb2)

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

## 5. 세션 모드

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

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

## 6. 성공 확인

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

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

## 7. 문제 해결

> [accordion] Claude의 404 / endpoint\_not\_found
>
> Anthropic과 [https://api.gravitex.ai를](https://api.gravitex.ai를) 사용하고 /v1을 붙이지 마세요. /v1/v1/messages는 경로가 중복된 것입니다. Claude를 OpenAI 호환 Responses 제공자로 등록하지 마세요.

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

> [accordion] Invalid API key for this provider
>
> Model providers에서 키 전체를 공백 없이 입력하고 저장하세요. 콘솔에서 유효한 키인지 확인합니다.

> [accordion] 제공자에 /models 인터페이스가 없다는 오류
>
> `Provider doesn't expose a /models endpoint at this base URL`이면 유형과 주소를 확인하세요. GPT는 [https://api.gravitex.ai/v1](https://api.gravitex.ai/v1), Claude는 [https://api.gravitex.ai입니다](https://api.gravitex.ai입니다). 계속 실패하면 모델 ID를 직접 입력합니다.

> [accordion] 카탈로그에서 먼저 API 키를 추가하라는 메시지
>
> `Add an API key for this provider before browsing the catalog`이면 제공자에 API 키를 입력하고 저장한 뒤 카탈로그를 여세요.

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

> [accordion] API 키는 어디에 저장되나요?
>
> macOS 키체인 또는 Windows 자격 증명 관리자에 저장됩니다. 공개 스크린샷, 대화, 저장소에 키를 노출하지 마세요.

### API 검증 명령(선택)

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

```bash GPT（Responses） theme={null}
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"}'
```

```bash Claude（Messages） theme={null}
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"}]}'
```

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

## 8. 관련 자료

* [GitHub Copilot App Releases](https://github.com/github/app/releases)
* [GravitexAI API 키 관리](https://maas.gravitex.ai/#/api-keys)
* [GravitexAI 모델 목록](https://maas.gravitex.ai/#/api-models)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.