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

> 환경 변수로 GitHub Copilot CLI에 GravitexAI GPT와 Claude를 연결하는 가이드

## 1. 제품 소개

GitHub Copilot CLI는 터미널에서 질의응답, 코드 수정, 계획 수립과 자율 실행을 지원하는 코딩 Agent입니다. **BYOK**로 GravitexAI의 GPT 또는 Claude 모델을 사용할 수 있습니다.

> [!NOTE]
>
> **CLI 1.0.9x**를 대상으로 하며 참고 버전은 \*\*1.0.98(2026년 10월)\*\*입니다. `COPILOT_PROVIDER_BASE_URL`을 설정하면 GitHub 로그인이나 Copilot 구독 없이 지정한 모델 서비스를 직접 호출합니다.

## 2. 요구 사항

* macOS 또는 Windows.
* npm 설치 시 **Node.js 22 이상**.
* Windows는 **PowerShell 6 이상** 권장.

## 3. 사전 조건

[GravitexAI 콘솔](https://maas.gravitex.ai/#/api-keys)에서 API 키(`sk-xxxxxxxxxx`)를 만들고, 계정에서 사용할 수 있는 모델 ID와 API 연결을 확인하세요.

## 4. 연결 설정

| 변수 | GPT | Claude |
| - | - | - |
| `COPILOT_PROVIDER_TYPE` | `openai` | `anthropic` |
| `COPILOT_PROVIDER_BASE_URL` | `https://api.gravitex.ai/v1` | `https://api.gravitex.ai`(**`/v1` 없음**) |
| `COPILOT_PROVIDER_WIRE_API` | `responses`(`/v1/responses`) | 설정 해제(`/v1/messages`) |
| `COPILOT_PROVIDER_API_KEY` | `sk-your-api-key` | 같은 키 |
| `COPILOT_MODEL` | 예: `gpt-5.5` | 예: `claude-sonnet-5-5` |

> [!WARNING]
>
> GPT와 Claude는 다른 프로토콜을 사용합니다. Claude는 `/v1/responses`를 지원하지 않으므로 anthropic과 루트 주소를 사용하세요. 터미널에는 한 세트만 적용됩니다. 모델 계열을 바꿀 때 프로토콜과 주소도 함께 전환하세요.

자주 쓰는 모델 예시:

* GPT: `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.3-codex`, `gpt-6-sol`.
* Claude: `claude-opus-5-5`, `claude-sonnet-5-5`, `claude-haiku-5-5`, `claude-fable-5-1`.

[모델 목록](https://maas.gravitex.ai/#/api-models)과 계정 권한을 기준으로 선택하거나 API로 조회하세요.

```bash theme={null}
curl -s https://api.gravitex.ai/v1/models -H "Authorization: Bearer sk-your-api-key"
```

## 5. 설치

### macOS

```bash theme={null}
# 방법 1: Homebrew (권장)
brew install --cask copilot-cli

# 방법 2: npm (Node.js 22 이상 필요)
npm install -g @github/copilot

# 방법 3: 공식 설치 스크립트
curl -fsSL https://gh.io/copilot-install | bash
```

### Windows

```powershell theme={null}
# 방법 1: WinGet (권장, PowerShell 6 이상)
winget install GitHub.Copilot

# 방법 2: npm (Node.js 22 이상 필요)
npm install -g @github/copilot
```

[공식 Releases](https://github.com/github/copilot-cli/releases)에서 실행 파일을 받아 사용할 수도 있습니다.

### 설치 확인

```bash theme={null}
copilot --version
# GitHub Copilot CLI 1.0.98.
```

## 6. 빠른 설정: 현재 터미널에만 적용

터미널을 닫으면 설정이 해제됩니다. `sk-your-api-key`를 실제 키로 바꾸고 OS와 모델 계열에 맞는 한 세트를 실행합니다.

> [tab] macOS (zsh / bash)
>
> **GPT**
>
> ```bash theme={null}
> export COPILOT_PROVIDER_TYPE=openai
> export COPILOT_PROVIDER_BASE_URL=https://api.gravitex.ai/v1
> export COPILOT_PROVIDER_API_KEY=sk-your-api-key
> export COPILOT_PROVIDER_WIRE_API=responses
> export COPILOT_MODEL=gpt-5.5
> copilot
> ```
>
> **Claude**
>
> ```bash theme={null}
> export COPILOT_PROVIDER_TYPE=anthropic
> export COPILOT_PROVIDER_BASE_URL=https://api.gravitex.ai
> export COPILOT_PROVIDER_API_KEY=sk-your-api-key
> unset COPILOT_PROVIDER_WIRE_API
> export COPILOT_MODEL=claude-sonnet-5-5
> copilot
> ```

> [tab] Windows PowerShell
>
> **GPT**
>
> ```powershell theme={null}
> $env:COPILOT_PROVIDER_TYPE = "openai"
> $env:COPILOT_PROVIDER_BASE_URL = "https://api.gravitex.ai/v1"
> $env:COPILOT_PROVIDER_API_KEY = "sk-your-api-key"
> $env:COPILOT_PROVIDER_WIRE_API = "responses"
> $env:COPILOT_MODEL = "gpt-5.5"
> copilot
> ```
>
> **Claude**
>
> ```powershell theme={null}
> $env:COPILOT_PROVIDER_TYPE = "anthropic"
> $env:COPILOT_PROVIDER_BASE_URL = "https://api.gravitex.ai"
> $env:COPILOT_PROVIDER_API_KEY = "sk-your-api-key"
> Remove-Item Env:COPILOT_PROVIDER_WIRE_API -ErrorAction SilentlyContinue
> $env:COPILOT_MODEL = "claude-sonnet-5-5"
> copilot
> ```

> [tab] Windows CMD
>
> ```bat theme={null}
> :: GPT
> set COPILOT_PROVIDER_TYPE=openai
> set COPILOT_PROVIDER_BASE_URL=https://api.gravitex.ai/v1
> set COPILOT_PROVIDER_API_KEY=sk-your-api-key
> set COPILOT_PROVIDER_WIRE_API=responses
> set COPILOT_MODEL=gpt-5.5
> copilot
> ```
>
> ```bat theme={null}
> :: Claude
> set COPILOT_PROVIDER_TYPE=anthropic
> set COPILOT_PROVIDER_BASE_URL=https://api.gravitex.ai
> set COPILOT_PROVIDER_API_KEY=sk-your-api-key
> set COPILOT_PROVIDER_WIRE_API=
> set COPILOT_MODEL=claude-sonnet-5-5
> copilot
> ```

## 7. 영구 설정

BYOK 제공자는 `settings.json`이 아닌 환경 변수로 설정합니다. 변수를 셸 설정 파일에 저장하면 유지됩니다. `copilot-gpt`, `copilot-claude` 두 명령을 만들면 매번 모든 변수를 입력하지 않고 모델 계열을 고를 수 있습니다.

### macOS: \~/.zshrc

```bash theme={null}
# 설정 파일 열기
open -e ~/.zshrc        # 또는 vim ~/.zshrc
```

파일 끝에 추가합니다.

```bash theme={null}
# ===== Gravitex x GitHub Copilot CLI =====
export GRAVITEX_API_KEY="sk-your-api-key"

# GPT: OpenAI 프로토콜, /v1/responses 사용
# 사용법: copilot-gpt [모델] [기타 copilot 인수...]
copilot-gpt() {
  local model="${1:-gpt-5.5}"; [ $# -gt 0 ] && shift
  COPILOT_PROVIDER_TYPE=openai \
  COPILOT_PROVIDER_BASE_URL=https://api.gravitex.ai/v1 \
  COPILOT_PROVIDER_API_KEY="$GRAVITEX_API_KEY" \
  COPILOT_PROVIDER_WIRE_API=responses \
  COPILOT_MODEL="$model" \
  copilot "$@"
}

# Claude: Anthropic 프로토콜, /v1/messages 사용
# 사용법: copilot-claude [모델] [기타 copilot 인수...]
copilot-claude() {
  local model="${1:-claude-sonnet-5-5}"; [ $# -gt 0 ] && shift
  COPILOT_PROVIDER_TYPE=anthropic \
  COPILOT_PROVIDER_BASE_URL=https://api.gravitex.ai \
  COPILOT_PROVIDER_API_KEY="$GRAVITEX_API_KEY" \
  COPILOT_MODEL="$model" \
  env -u COPILOT_PROVIDER_WIRE_API copilot "$@"
}
```

설정을 다시 불러온 뒤 사용합니다.

```bash theme={null}
source ~/.zshrc
```

```bash theme={null}
copilot-gpt                         # 기본값: gpt-5.5
copilot-gpt gpt-5.3-codex           # 모델 지정
copilot-claude                      # 기본값: claude-sonnet-5-5
copilot-claude claude-opus-5-5 --yolo   # 모델 지정 + 확인 생략 모드
```

> [!TIP]
>
> 한 계열만 사용한다면 6절의 환경 변수를 \~/.zshrc에 저장하고 copilot을 직접 실행해도 됩니다. GPT에서 Claude로 바꿀 때는 COPILOT\_PROVIDER\_WIRE\_API를 지우세요.

### Windows: PowerShell Profile

```powershell theme={null}
# 프로필 파일이 없으면 만들고 메모장으로 열기
if (!(Test-Path $PROFILE)) { New-Item -Path $PROFILE -ItemType File -Force }
notepad $PROFILE
```

끝에 추가합니다.

```powershell theme={null}
# ===== Gravitex x GitHub Copilot CLI =====
$env:GRAVITEX_API_KEY = "sk-your-api-key"

# GPT: OpenAI 프로토콜, /v1/responses 사용
# 사용법: copilot-gpt [모델] [기타 copilot 인수...]
function copilot-gpt {
    param([string]$Model = "gpt-5.5", [Parameter(ValueFromRemainingArguments)]$Rest)
    $env:COPILOT_PROVIDER_TYPE = "openai"
    $env:COPILOT_PROVIDER_BASE_URL = "https://api.gravitex.ai/v1"
    $env:COPILOT_PROVIDER_API_KEY = $env:GRAVITEX_API_KEY
    $env:COPILOT_PROVIDER_WIRE_API = "responses"
    $env:COPILOT_MODEL = $Model
    copilot @Rest
}

# Claude: Anthropic 프로토콜, /v1/messages 사용
# 사용법: copilot-claude [모델] [기타 copilot 인수...]
function copilot-claude {
    param([string]$Model = "claude-sonnet-5-5", [Parameter(ValueFromRemainingArguments)]$Rest)
    $env:COPILOT_PROVIDER_TYPE = "anthropic"
    $env:COPILOT_PROVIDER_BASE_URL = "https://api.gravitex.ai"
    $env:COPILOT_PROVIDER_API_KEY = $env:GRAVITEX_API_KEY
    Remove-Item Env:COPILOT_PROVIDER_WIRE_API -ErrorAction SilentlyContinue
    $env:COPILOT_MODEL = $Model
    copilot @Rest
}
```

PowerShell을 다시 열거나 `. $PROFILE`을 실행합니다. 사용법은 macOS와 같습니다.

> [!NOTE]
>
> Profile 스크립트 실행이 차단되면 6절의 임시 설정을 사용하세요. Profile이 필요하다면 컴퓨터 관리 정책에 맞게 스크립트 실행 정책을 설정합니다.

### Windows: 한 모델 계열을 위한 사용자 환경 변수

```powershell theme={null}
# GPT 예시: 저장 후 터미널 다시 열기
[Environment]::SetEnvironmentVariable("COPILOT_PROVIDER_TYPE", "openai", "User")
[Environment]::SetEnvironmentVariable("COPILOT_PROVIDER_BASE_URL", "https://api.gravitex.ai/v1", "User")
[Environment]::SetEnvironmentVariable("COPILOT_PROVIDER_API_KEY", "sk-your-api-key", "User")
[Environment]::SetEnvironmentVariable("COPILOT_PROVIDER_WIRE_API", "responses", "User")
[Environment]::SetEnvironmentVariable("COPILOT_MODEL", "gpt-5.5", "User")
```

저장 후 터미널을 다시 여세요. 삭제하려면 각 명령의 두 번째 인수를 `$null`로 바꾸어 다시 실행합니다.

## 8. 확인 생략 모드와 권한

기본적으로 읽기 전용 작업은 자동 승인되고 파일 쓰기와 명령 실행은 확인을 요청합니다. 아래 설정으로 승인 방식을 바꿀 수 있습니다.

### 1. YOLO: 한 번 실행할 때 확인 생략

```bash theme={null}
copilot --yolo          # 확인 생략 모드
copilot --allow-all     # --yolo와 동일
```

`--yolo` / `--allow-all`은 다음 옵션의 조합입니다.

| 옵션 | 효과 |
| - | - |
| `--allow-all-tools` | 파일 쓰기, 명령, MCP 등 도구 실행 확인 생략 |
| `--allow-all-paths` | 모든 경로 허용. 기본 범위는 현재 폴더와 하위 폴더 |
| `--allow-all-urls` | 모든 URL 허용 |

YOLO는 승인 설정입니다. 작업 완료까지 계속 자율 실행하려면 \*\*`--autopilot`\*\*도 추가합니다.

```bash theme={null}
copilot --yolo --autopilot
```

### 2. 세션에서 전환

| 명령 | 효과 |
| - | - |
| `/allow-all` | 현재 세션에서 모든 권한 허용 |
| `/permissions` | manual, assisted, allow-all 모드 전환 |

### 3. 기본 권한 모드 저장

```bash theme={null}
# 새 대화형 세션의 기본 권한을 allow-all로 설정
copilot config defaultPermissionMode allow-all

# 선택: 새 세션을 기본 autopilot 모드로 시작
copilot config defaultMode autopilot
```

`~/.copilot/settings.json`(Windows: `%USERPROFILE%\.copilot\settings.json`)에 저장되며 다음과 같습니다.

```json theme={null}
{
  "defaultPermissionMode": "allow-all",
  "defaultMode": "autopilot"
}
```

기본값 복구:

```bash theme={null}
copilot config defaultPermissionMode manual
copilot config defaultMode interactive
```

### 4. 비대화형 스크립트와 CI

`-p`에는 `--allow-all-tools` 또는 `--yolo`가 필요합니다.

```bash theme={null}
copilot -p "main.go에 단위 테스트 추가" --yolo -s
```

`COPILOT_ALLOW_ALL=true`도 사용할 수 있습니다. 이 값은 현재 디렉터리도 신뢰하고 플러그인, MCP, hooks를 불러옵니다.

> [!WARNING]
>
> 모두 허용하면 확인 없이 파일을 수정/삭제하고 명령을 실행할 수 있습니다. 신뢰할 수 있고 Git으로 관리되는 프로젝트에서 필요할 때만 사용하고 변경 내용을 확인하세요.

## 9. 일상 사용

```bash theme={null}
# 대화형 모드
copilot

# 한 번 질문 후 종료 (-s는 답변만 출력)
copilot -p "이 프로젝트의 디렉터리 구조를 설명해 줘" -s --allow-all-tools

# 이번 실행에서 모델 지정 (같은 프로토콜 필요)
copilot --model gpt-5.4

# 최근 세션 재개
copilot --continue

# 계획 모드: 검토 후 실행
copilot --mode plan
```

| 세션 명령 | 효과 |
| - | - |
| `/model` | 모델 전환 |
| `/allow-all` | 모든 권한 허용 |
| `/permissions` | 권한 모드 변경 |
| `/help` | 명령 목록 |

## 10. 검증과 문제 해결

### 연결 확인

```bash theme={null}
# 6절의 환경 변수 설정 후 실행
copilot -p "Reply with exactly: OK" -s --allow-all-tools
```

인증, 프로토콜, 모델 오류 없이 OK가 반환되면 요청이 정상 작동합니다. 영구 설정 함수를 검증할 때는 명령의 copilot을 `copilot-gpt gpt-5.5` 또는 `copilot-claude claude-sonnet-5-5`로 바꿉니다.

> [accordion] Model 'claude-xxx' not found on provider ... (HTTP 404)
>
> Claude를 openai + responses로 설정한 경우입니다. anthropic 유형으로 바꾸세요.

> [accordion] Claude의 404 또는 /v1/v1/messages
>
> Anthropic Base URL에서 /v1을 제거하고 [https://api.gravitex.ai를](https://api.gravitex.ai를) 사용하세요.

> [accordion] GPT의 404
>
> OpenAI 호환 주소에 /v1을 포함해야 합니다. [https://api.gravitex.ai/v1을](https://api.gravitex.ai/v1을) 사용하세요.

> [accordion] 401 / Invalid API key
>
> 키, 잔액, 모델 권한을 확인하세요. curl로 /v1/models를 조회할 수도 있습니다.

> [accordion] 계속 GitHub 로그인을 요구함
>
> COPILOT\_PROVIDER\_BASE\_URL이 적용되지 않았습니다. `echo $COPILOT_PROVIDER_BASE_URL`, PowerShell에서는 `$env:COPILOT_PROVIDER_BASE_URL`로 확인하세요.

> [accordion] \~/.zshrc 변경이 적용되지 않음
>
> source \~/.zshrc를 실행하거나 터미널을 다시 엽니다.

### 사용 가능한 옵션 확인

```bash theme={null}
copilot help providers     # BYOK 설정 도움말
copilot help environment   # 환경 변수
copilot help permissions   # 권한 도움말
copilot help config        # settings.json 설정 항목
```

## 11. 관련 자료

* [GitHub Copilot CLI](https://github.com/github/copilot-cli)
* [GravitexAI 키 관리](https://maas.gravitex.ai/#/api-keys)
* [GravitexAI 모델 목록](https://maas.gravitex.ai/#/api-models)
* [GitHub Copilot App 설정](https://docs.gravitex.ai/ko/integrations/github-copilot-app.md)


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