GitHub Copilot CLI

1. 제품 소개

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

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 콘솔에서 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`

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.

모델 목록과 계정 권한을 기준으로 선택하거나 API로 조회하세요.

curl -s https://api.gravitex.ai/v1/models -H "Authorization: Bearer sk-your-api-key"

5. 설치

macOS

# 방법 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

# 방법 1: WinGet (권장, PowerShell 6 이상)
winget install GitHub.Copilot

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

공식 Releases에서 실행 파일을 받아 사용할 수도 있습니다.

설치 확인

copilot --version
# GitHub Copilot CLI 1.0.98.

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

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

macOS (zsh / bash)
Windows PowerShell
Windows CMD

GPT

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

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

GPT

$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

$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

:: 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

:: 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

# 설정 파일 열기
open -e ~/.zshrc        # 또는 vim ~/.zshrc

파일 끝에 추가합니다.

# ===== 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 "$@"
}

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

source ~/.zshrc

copilot-gpt                         # 기본값: gpt-5.5
copilot-gpt gpt-5.3-codex           # 모델 지정
copilot-claude                      # 기본값: claude-sonnet-5-5
copilot-claude claude-opus-5-5 --yolo   # 모델 지정 + 확인 생략 모드

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

Windows: PowerShell Profile

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

끝에 추가합니다.

# ===== 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와 같습니다.

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

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

# 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: 한 번 실행할 때 확인 생략

copilot --yolo          # 확인 생략 모드
copilot --allow-all     # --yolo와 동일

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

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

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

copilot --yolo --autopilot

2. 세션에서 전환

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

3. 기본 권한 모드 저장

# 새 대화형 세션의 기본 권한을 allow-all로 설정
copilot config defaultPermissionMode allow-all

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

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

{
  "defaultPermissionMode": "allow-all",
  "defaultMode": "autopilot"
}

기본값 복구:

copilot config defaultPermissionMode manual
copilot config defaultMode interactive

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

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

copilot -p "main.go에 단위 테스트 추가" --yolo -s

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

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

9. 일상 사용

# 대화형 모드
copilot

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

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

# 최근 세션 재개
copilot --continue

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

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

10. 검증과 문제 해결

연결 확인

# 6절의 환경 변수 설정 후 실행
copilot -p "Reply with exactly: OK" -s --allow-all-tools

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

Model 'claude-xxx' not found on provider ... (HTTP 404)

Claude를 openai + responses로 설정한 경우입니다. anthropic 유형으로 바꾸세요.

Claude의 404 또는 /v1/v1/messages

Anthropic Base URL에서 /v1을 제거하고 https://api.gravitex.ai를 사용하세요.

GPT의 404

OpenAI 호환 주소에 /v1을 포함해야 합니다. https://api.gravitex.ai/v1을 사용하세요.

401 / Invalid API key

키, 잔액, 모델 권한을 확인하세요. curl로 /v1/models를 조회할 수도 있습니다.

계속 GitHub 로그인을 요구함

COPILOT_PROVIDER_BASE_URL이 적용되지 않았습니다. echo $COPILOT_PROVIDER_BASE_URL, PowerShell에서는 $env:COPILOT_PROVIDER_BASE_URL로 확인하세요.

~/.zshrc 변경이 적용되지 않음

source ~/.zshrc를 실행하거나 터미널을 다시 엽니다.

사용 가능한 옵션 확인

copilot help providers     # BYOK 설정 도움말
copilot help environment   # 환경 변수
copilot help permissions   # 권한 도움말
copilot help config        # settings.json 설정 항목

대화형 AI

프로그래밍 개발

AI 에이전트

기술 엔지니어링

번역

1. 제품 소개

2. 요구 사항

3. 사전 조건

4. 연결 설정

5. 설치

macOS

Windows

설치 확인

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

7. 영구 설정

macOS: ~/.zshrc

Windows: PowerShell Profile

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

8. 확인 생략 모드와 권한

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

2. 세션에서 전환

3. 기본 권한 모드 저장

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

9. 일상 사용

10. 검증과 문제 해결

연결 확인

사용 가능한 옵션 확인

11. 관련 자료

​1. 제품 소개

​2. 요구 사항

​3. 사전 조건

​4. 연결 설정

​5. 설치

​macOS

​Windows

​설치 확인

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

​7. 영구 설정

​macOS: ~/.zshrc

​Windows: PowerShell Profile

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

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

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

​2. 세션에서 전환

​3. 기본 권한 모드 저장

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

​9. 일상 사용

​10. 검증과 문제 해결

​연결 확인

​사용 가능한 옵션 확인

​11. 관련 자료

1. 제품 소개

2. 요구 사항

3. 사전 조건

4. 연결 설정

5. 설치

macOS

Windows

설치 확인

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

7. 영구 설정

macOS: ~/.zshrc

Windows: PowerShell Profile

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

8. 확인 생략 모드와 권한

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

2. 세션에서 전환

3. 기본 권한 모드 저장

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

9. 일상 사용

10. 검증과 문제 해결

연결 확인

사용 가능한 옵션 확인

11. 관련 자료