QLHazyCoder/copilot-api

영어 | 중국어

참고 사항

이 포크에 대하여
본 프로젝트는 ericc-ch/copilot-api에서 포크되었습니다. 원작자가 유지보수를 중단하고 더 이상 새로운 API를 지원하지 않기 때문에, 저희가 이를 재설계하고 다시 작성했습니다.
원래 작업과 기여를 해주신 @ericc-ch 님께 특별히 감사드립니다!

경고

이것은 GitHub Copilot API의 리버스 엔지니어링(reverse-engineered) 프록시입니다. GitHub에서 지원하지 않으며, 예기치 않게 작동이 중단될 수 있습니다. 사용에 대한 모든 위험은 사용자 본인에게 있습니다.

경고

GitHub 보안 공지:

Copilot을 과도하게 자동화하거나 스크립트 방식으로 사용하는 경우(자동 도구를 통한 빠른 요청 또는 대량 요청 포함) GitHub의 남용 감지 시스템이 작동할 수 있습니다.

GitHub Security로부터 경고를 받을 수 있으며, 추가적인 비정상 활동은 Copilot 접근의 일시적 정지로 이어질 수 있습니다.

GitHub는 과도한 자동화된 대규모 활동이나 인프라에 부당한 부담을 주는 모든 활동에 대해 자사 서버 사용을 금지합니다.

다음 사항을 검토해 주십시오:

계정 제한을 피하기 위해 이 프록시를 책임감 있게 사용하십시오.

참고: 만약 opencode를 사용하고 있다면, 본 프로젝트는 필요하지 않습니다. Opencode는 GitHub Copilot 제공업체를 기본적으로 지원합니다.

OpenAI와 Anthropic, 그리고 Gemini와 호환되는 인터페이스를 노출하는 GitHub Copilot API의 리버스 엔지니어링 프록시입니다. 게이트웨이는 모델별 supported_endpoints에 따라 라우팅을 수행하며 필요한 경우 프로토콜 변환을 수행합니다. 따라서 OpenAI Chat Completions, OpenAI Responses, Anthropic Messages 또는 Gemini generateContent 스타일 호출을 사용하는 클라이언트들은 모두 동일한 백엔드(Claude Code 포함)와 작동할 수 있습니다.

본 프로젝트는 단일 경로 패스스루 프록시가 아니라 역량 기반 라우팅 게이트웨이로 현재 작동합니다:

• OpenAI / Anthropic / Gemini 호환 인그레스 엔드포인트를 노출합니다.
• 모델의 supported_endpoints로부터 업스트림 엔드포인트 경로를 동적으로 선택합니다.

. - 인그레스 프로토콜과 최종 업스트림 프로토콜이 다를 수 있습니다(양방향 형식 변환 포함).

flowchart TB
subgraph Clients["클라이언트"] 
C1[OpenAI 호환 클라이언트]
...

• 모델이 메시지를 지원하는 경우 -> /v1/messages 사용

• 그렇지 않고, 모델이 응답을 지원하는 경우 -> 번역하여 /responses 사용

• 그 외의 경우 -> 번역하여 /chat/completions 사용

• 모델이 채팅을 지원하는 경우 -> /chat/completions 사용

• 그렇지 않고, 모델이 메시지를 지원하는 경우 -> /v1/messages로 폴백(fallback)

• 그렇지 않고, 모델이 응답을 지원하는 경우 -> /responses로 폴백(fallback)

• 모델이 supported_endpoints를 선언했으나 일치하는 것이 없는 경우 -> 400 반환 - 엔드포인트 메타데이터가 누락되거나 비어 있는 경우 -> 채팅 경로로 기본 설정

• 응답을 지원할 때만 허용됨

• 지원하지 않는 경우 -> 직접 400 (다중 엔드포인트 폴백 없음)

• 고정된 채팅 전용 설계: Gemini 요청은 항상 /chat/completions로 번역됨

• 실행 순서는 다음과 같습니다: 먼저 모델의 기능을 검증하고, 그 다음 Gemini -> Chat 페이로드로 변환합니다.

• 채팅을 지원하지 않는 경우 -> 직접 400 (메시지/응답 폴백 없음)

• 현재는 contents.parts.text를 통한 텍스트 입력만 가능

다중 프로토콜 인그레스: OpenAI Chat, OpenAI Responses, Anthropic Messages, 그리고 Gemini 호환 엔드포인트 지원.기능 기반 라우팅: 모델의 supported_endpoints에 따라 동적으로 라우팅하며, 하드코딩된 모델 이름 라우팅은 사용하지 않습니다.양방향 번역 계층: Anthropic <-> Chat, Anthropic <-> Responses, 그리고 Chat <-> Gemini 호환 번역을 지원합니다.웹 계정 관리: /admin 경로에서 여러 GitHub 계정을 추가하고 관리할 수 있습니다.다중 계정 지원: 서버를 재시작하지 않고도 활성 계정을 전환할 수 있습니다.Docker 우선 배포: 영구적인 설정을 가진 컨테이너 중심의 배포 방식을 제공합니다.사용량 모니터링: /usage에서 사용량과 할당량을 검사할 수 있습니다.속도 제한 제어: 구성 가능한 스로틀링 및 대기 전략을 제공합니다.계정 유형 지원: 개별 / 비즈니스 / 엔터프라이즈 플랜을 지원합니다.추적 상관관계(Trace correlation): 모든 인바운드 요청은 x-trace-id를 포함하며, 이 ID는 업스트림으로 x-request-id로 전파되고, 최종 종단 간 진단(end-to-end diagnostics)을 위해 /x-agent-task-id가 사용됩니다.

# 서버 시작하기
docker compose up -d
# 로그 보기
...

이후 **http://localhost:4141/admin**에 접속하세요. 처음 실행하는 경우, Admin 관리 시크릿을 생성하기 위해 /admin/setup으로 리디렉션됩니다. 이 설정 경로는 시크릿이 존재할 때까지 localhost에서만 접근 가능합니다. 설정을 완료한 후에는 /admin/login에서 로그인하고 GitHub 계정을 추가하세요.

docker run -d \
--name copilot-api \
-p 4141:4141 \
...

• Docker를 사용하여 서버 시작하기
• 브라우저에서 http://localhost:4141/admin 열기
• 첫 실행이며 Admin 시크릿이 아직 구성되지 않은 경우, localhost에서 /admin/setup에서 일회성 설정을 완료하세요. - Admin 관리 시크릿으로 /admin/login에서 로그인하기 -

⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.

: dedupe only when the same conversation keeps the same endpoint

• model

• multiplier

; 만약 이 필드들 중 어느 하나라도 변경되면, 새로운 로컬 로그 행이 생성되고 로컬 사용량 요약이 다시 새로 고쳐집니다.

• 로컬 Quota Delta 열 추가:
  max(lastPremiumUsed - firstPremiumUsed, 0) + multiplier

• 첫 번째 요청은 해당 행의 승수(multiplier)로 계산되며, 이후 요청들은 관찰된 상위 사용량 프리미엄 증가분을 더합니다.

• source 필터링(all/request) 및 커서 페이지네이션 지원; endpoint는 현재 표시 전용이며 독립적인 필터가 아닙니다. - 구성 가능한 사용량 테스트/폴링 간격; 기본 간격은 설정에서 가져옵니다(기본값 10분), 그리고 테스트 요청에는 gpt-4o를 사용합니다. - 월별 정리 작업은 정확한 크론 트리거가 아닌, 지연된 쓰기 시점(새 로그가 추가될 때 실행)에 이루어집니다.

• 이 모드는 로컬 usage_logs 동작 및 요약 새로 고침 전략에만 영향을 미치며, /usage에서 반환되는 상위 Copilot 청구 데이터는 변경하지 않습니다.

• 모델 매핑(model mappings) 추가, 복사 및 삭제 기능.

• 클라이언트가 사용하는 별칭을 실제 Copilot 모델에 매핑합니다.

• 대상 모델 옵션은 /v1/models에서 동적으로 로드될 수 있습니다.

• 전역 속도 제한(rate-limit) 및 관련 관리 설정을 수정합니다 (환경 변수가 여전히 우선권을 가집니다).

• 서버 측 자동 컨텍스트 압축을 활성화하고 사용자 인터페이스 트리거 설정을 조정할 수 있습니다.

• 공식 Claude의 정확도를 위해 페이지에서 anthropicApiKey를 구성합니다(/v1/messages/count_tokens). - 관리자 보안 상태, 세션 기간 및 현재 관리 시크릿 출처를 확인합니다.

• 사용량 테스트 간격 설정이 포함됩니다.

• 현재 활성 계정의 로컬 사용량 로그 목록을 지울 수 있는 버튼이 포함됩니다. 과거 월별 로그는 매월 1일 이후 첫 번째 새 쓰기 작업 시 자동으로 정리됩니다.

• chat/completions, responses, messages, 그리고 gemini에 대한 인앱 호환성 테이블이 포함됩니다.

• GPT-Load나 New API와 같은 도구에 대한 권장 엔드포인트 그룹화를 요약합니다.
• 관리자 UI(Admin UI)에서 프로젝트 간 통합을 위한 현재 빠른 참고 자료 역할을 합니다.

services:
copilot-api:
image: ghcr.io/qlhazycoder/copilot-api:latest
...

만약 환경 변수를 통해 RATE_LIMIT / RATE_LIMIT_WAIT가 설정되지 않았다면, 관리 페이지의 Settings 탭에서 구성할 수 있습니다. 환경 변수는 저장된 웹 설정보다 우선합니다.

또한 /v1 접두사 없이 호환성 별칭으로도 사용할 수 있습니다:
: /chat/completions, /responses, /models, /embeddings.

| Endpoint | Method | Description |
|---|---|
/v1beta/models/{model}:generateContent | POST | Gemini와 호환되는 비스트림(non-stream) 엔트리 포인트로, 내부적으로 /chat/completions에 고정됩니다. |
/v1beta/models/{model}:streamGenerateContent | POST | Gemini와 호환되는 스트림(stream) 엔트리 포인트로, 내부적으로 /chat/completions에 고정되며 SSE를 통해 반환됩니다. |

참고: Gemini 엔트리 포인트는 현재 채팅 전용이며 텍스트 입력(contents.parts.text)에 초점을 맞추고 있습니다. 모델이 채팅을 지원하지 않는 경우, 직접적으로 400 에러를 반환합니다.

| Endpoint | Method | Description |
|---|---|
/admin | GET | 계정 관리 웹 UI (Admin 비밀번호 로그인으로 보호되며, 첫 설정 시에는 localhost 전용 /admin/setup을 사용합니다.) |
/usage | GET | Copilot 사용 통계 및 할당량 |
/token | GET | 현재 Copilot 토큰

이 프로젝트는 Claude Code / Codex 도구 프로토콜 호환 레이어를 완전히 구현하지 않았습니다. 도구 지원은 현재 최선의 노력(best-effort)이며, GitHub Copilot이 안정적으로 수용하는 도구 형태에 한정됩니다.

잘 지원되는 기능: OpenAI와 호환되거나 Anthropic과 호환되는 요청을 통해 전달된 표준 function 도구.
내장 응답 도구 (Built-in Responses tools): 업스트림 모델/엔드포인트가 지원하는 경우, web_search, web_search_preview, file_search, code_interpreter, image_generation, 그리고 local_shell과 같은 Copilot/OpenAI 스타일의 내장 도구에 대한 지원이 존재합니다.
특수 호환성: 사용자 정의 apply_patch는 더 나은 호환성을 위해 function 도구로 정규화됩니다.
제한적인 파일 편집 호환성: write, write_file, writefiles, edit, edit_file, multi_edit, 그리고 multiedit과 같은 일반적인 사용자 정의 파일 편집 도구 이름은 프록시에서 즉시 누락되지 않도록 function 도구로 정규화됩니다.
보장되지 않는 기능: Claude Code, Codex, superpowers가 사용하는 스킬별 도구.

, 또는 다른 에이전트 프레임워크는 Copilot이 상위 레벨에서 지원하지 않는 클라이언트별 스키마, 결과 형식 또는 도구 실행 의미론에 의존하는 경우 여전히 실패할 수 있습니다.현재 제한 사항: 이 프록시는 아직 모든 Claude Code 또는 Codex 파일 도구에 대한 완전한 엔드투엔드 호환성 계층을 제공하지 않습니다. 만약 어떤 스킬이 독점적인 도구 계약에 의존한다면, 추가 어댑터 작업이 여전히 필요합니다.

Claude Code가 이 프록시를 사용하도록 구성하려면 .claude/settings.json 파일을 생성하세요:

{
"env": {"ANTHROPIC_BASE_URL": "http://localhost:4141",
...
}

모델 선택은 더 이상 .claude/settings.json에 하드코딩될 필요가 없습니다.

/admin을 열고, Model Mappings 탭으로 전환한 다음, Claude Code 모델 별칭을 사용하려는 실제 Copilot 모델에 매핑하세요.

이것은 haiku, sonnet, opus와 같이 날짜가 지정된 Claude 모델 ID 또는 다른 클라이언트용 모델 이름을 변경할 때마다 로컬 Claude Code 설정을 변경하지 않고도 haiku 등을 라우팅하는 권장 방법입니다.

더 많은 옵션: Claude Code 설정

Claude Code가 SubagentStart 훅 중에 추가 마커를 주입하여 copilot-api