theblixguy/xcode-copilot-server

Xcode에서 GitHub Copilot을 커스텀 모델 제공자(custom model provider)로 사용하거나, Claude Agent 및 Codex Agent의 백엔드로 사용할 수 있게 해주는 프록시 API 서버입니다.

경고

대부분의 다른 Copilot 프록시 서버(원격 또는 로컬)는 비공개 Copilot API를 역공학(reverse-engineering)하고 User-Agent를 위조하여 VS Code인 것처럼 속이는 방식으로 작동합니다. GitHub의 남용 탐지 시스템은 이러한 유형의 사용을 감지하여 Copilot 접근을 제한하거나 정지할 수 있습니다. 프록시 프로젝트 자체에서도 이러한 위험에 대해 경고하고 있습니다. 이러한 서버의 사용은 피해야 합니다. 본 서버는 Copilot을 기반으로 구축할 수 있는 공식적인 방법인 공식 Copilot SDK를 사용합니다.

Xcode 26은 서드파티 LLM 제공자(third-party LLM providers) 지원을 추가했지만, 기본적으로는 ChatGPT와 Claude만 지원합니다. GitHub Copilot 구독이 있더라도 이를 사용할 수 있는 내장된 방법은 없습니다.

이 서버는 GitHub Copilot SDK를 래핑(wrap)하여 Xcode가 통신할 수 있는 API로 노출합니다. 이 서버는 SDK 통합 및 프로토콜 변환을 처리하는 copilot-sdk-proxy를 기반으로 구축되었습니다. 통합 테스트는 llm-mock-server를 대상으로 실행됩니다. 다음 세 가지 제공자를 지원합니다:

OpenAI(기본값): OpenAI 호환 완료(completions) API를 노출하여 Xcode가 Copilot을 커스텀 모델 제공자로 사용할 수 있게 합니다. Xcode가 도구 실행(tool execution)을 직접 처리합니다.
Claude: Anthropic 호환 API를 노출하여 Xcode가 Copilot을 Claude Agent의 백엔드로 사용할 수 있게 합니다. 내장된 도구 브리지(tool bridge)가 도구 호출을 가로채 실행을 위해 Xcode로 다시 라우팅합니다.
Codex: OpenAI Responses 호환 API를 노출하여 Xcode가 Copilot을 Codex Agent의 백엔드로 사용할 수 있게 합니다. Claude와 동일한 도구 브리지를 사용합니다.

OpenAI 모드에서 서버는 또한 Xcode의 내장 MCP 도구(xcrun mcpbridge를 통해)에 연결하여 Copilot이 프로젝트의 빌드 로그, 인덱스 및 기타 컨텍스트에 접근할 수 있도록 합니다. 이를 위해서는 Xcode 26.3 이상이 필요합니다. Claude와 Codex는 자체 에이전트를 통해 내부적으로 MCP를 처리합니다.

Node.js 22 이상과 GitHub Copilot 구독이 필요합니다.

**1. 다음 중 하나로 인증하세요 (하나만 필요합니다):

copilot login # Copilot CLI
gh auth login # GitHub CLI

또는 유효한 세밀한 권한 부여(fine-grained) Copilot 액세스 토큰이 포함된 GITHUB_TOKEN 환경 변수(environment variable)를 설정하세요.

2. 설치:

npm install -g xcode-copilot-server

3. 서버 시작:

xcode-copilot-server

서버는 기본적으로 자동 모드(auto mode)로 실행되며, 세 가지 프로바이더(provider)를 모두 등록하고 Claude 및 Codex 설정을 자동으로 패치(auto-patch)합니다. Xcode에서 사용하려는 프로바이더를 선택하고 아래의 설정 과정을 따르세요.

💡 팁

하나의 프로바이더만 필요한 경우, --proxy를 사용하여 단일 프로바이더만 실행할 수 있습니다 (예: xcode-copilot-server --proxy claude). 자세한 내용은 CLI 레퍼런스를 참조하세요.

OpenAI (커스텀 모델 프로바이더)

Xcode에서 Settings > Intelligence > Add a provider로 이동합니다.
"Locally hosted"를 선택하고 포트(port)를 8080(또는 사용자가 선택한 포트)으로 설정합니다.
"Copilot"과 같은 설명을 입력하고 저장합니다.

도구 호출(tool calling)을 활성화하려면, 해당 프로바이더를 선택하고 "Advanced" 아래에서 "Allow tools"를 활성화하세요. Xcode의 MCP 도구(Xcode 26.3 이상)를 연결하려면 "Model Context Protocol" 아래에서 "Xcode Tools"를 활성화하세요.

Claude (Claude Agent)

Xcode에서 Settings > Intelligence > Anthropic > Claude Agent로 이동합니다.
Claude Agent를 활성화하고 API 키로 로그인합니다 (호출이 서버를 통해 프록시(proxied)되므로, 키는 임의의 텍스트여도 상관없습니다).

도구 브리지(tool bridge)는 기본적으로 활성화되어 있습니다 (설정 파일 내 toolBridge: true). 이는 Copilot 세션으로부터의 도구 호출을 가로채서 Xcode로 전달하므로, Claude Agent가 IDE를 통해 파일을 읽고, 코드를 검색하며, 편집을 수행할 수 있습니다.

Codex (Codex Agent)

Xcode에서 Settings > Intelligence > OpenAI > Codex Agent로 이동합니다.
Codex Agent를 활성화하고 API 키로 로그인합니다 (호출이 서버를 통해 프록시(proxied)되므로, 키는 임의의 텍스트여도 상관없습니다).

새로운 환경 변수를 적용하기 위해 Xcode를 재시작해야 할 수도 있습니다.

도구 브리지는 Claude와 동일한 방식으로 작동하며, 도구 호출을 가로채서 실행을 위해 Xcode로 다시 라우팅(routing)합니다.

💡 팁

자동 시작/종료와 함께 서버를 백그라운드에서 실행하려면 아래의 Launchd agent 섹션을 참조하세요.

서버는 config.json5 파일에서 설정을 읽어옵니다. 기본적으로는 번들된 파일을 사용하지만, --config 옵션을 사용하여 사용자 정의 파일을 지정할 수 있습니다:

xcode-copilot-server --config ./my-config.json5

설정 파일은 주석과 trailing comma(마지막 쉼표)를 지원하는 JSON5 형식을 사용합니다. 자동 모드(auto mode)에서는 세 가지 프로바이더(provider) 섹션이 모두 활성화됩니다. 단일 프로바이더 모드(--proxy)에서는 지정된 섹션만 사용됩니다:

{
openai: {
// Xcode가 도구 실행을 직접 제어하므로, 별도의 도구 브릿지(tool bridge)가 필요하지 않습니다.
...

자동 모드에서는 Claude와 Codex 설정이 시작 시 패치(patch)되고 종료 시 복구(restore)됩니다. Claude의 경우, 서버는 ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/ 경로에 settings.json을 생성(또는 업데이트)하여 서버를 가리키도록 합니다. Codex의 경우, Xcode(및 Xcode가 생성하는 모든 Codex 프로세스)가 서버에 도달할 수 있도록 launchctl setenv를 통해 OPENAI_BASE_URL 및 OPENAI_API_KEY를 설정합니다.

OpenAI는 Xcode의 내장된 로컬 호스트 프로바이더(locally hosted provider) 지원 기능을 사용하므로 별도의 설정 패치가 필요하지 않습니다.

자동 패치 대신 직접 설정을 구성하고 싶다면 아래의 수동 단계를 참조하세요.

Claude

~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/ 경로에 settings.json을 생성합니다:

{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:8080",
...

포트는 사용자의 --port 플래그와 일치하도록 설정하세요 (기본값 8080). 인증 토큰(auth token)은 비어 있지 않은 임의의 문자열이면 됩니다.

또한 서버를 시작하지 않고도 설정을 패치하거나 복구하기 위해 patch-settings 및 restore-settings 서브 명령(subcommands)을 사용할 수 있습니다:

xcode-copilot-server patch-settings --proxy claude --port 8080
xcode-copilot-server restore-settings --proxy claude

Codex

launchctl을 통해 환경 변수를 설정합니다:

launchctl setenv OPENAI_BASE_URL http://localhost:8080/v1
launchctl setenv OPENAI_API_KEY 12345

포트는 사용자의 --port 플래그와 일치하도록 설정하세요.

플래그 (기본값 8080). API 키는 비어 있지 않은 임의의 문자열이면 됩니다. 작업이 끝난 후 원래 값으로 복구하려면 다음을 실행하세요:

launchctl unsetenv OPENAI_BASE_URL
launchctl unsetenv OPENAI_API_KEY

서버를 시작하지 않고도 이를 수행하기 위해 patch-settings 및 restore-settings 하위 명령 (subcommands)을 사용할 수도 있습니다:

xcode-copilot-server patch-settings --proxy codex --port 8080
xcode-copilot-server restore-settings --proxy codex

에이전트 스킬 (Agent skills)은 AI 코딩 에이전트에 사용자 정의 지침 (custom instructions)과 파일 컨텍스트 (file context)를 추가하기 위한 개방형 표준입니다. 세 가지 제공업체 모두 Copilot SDK 세션을 통해 이를 지원하며, 각 에이전트는 고유한 스킬 경로 (skill paths)를 가집니다:

에이전트 (Agent)	프로젝트 스킬 (Project skills)	개인 스킬 (Personal skills)
Copilot	`.github/skills/` , `.claude/skills/`	`~/.copilot/skills/`
Claude	`.claude/skills/`	`~/.claude/skills/`
Codex	`.codex/skills/`	`~/.codex/skills/`

매번 수동으로 서버를 시작하는 대신, launchd 에이전트로 설치할 수 있습니다. 이는 macOS 소켓 활성화 (socket activation)를 사용하므로, 무언가가 포트에 연결될 때 (예: Xcode가 첫 번째 요청을 보낼 때) 서버가 자동으로 시작되며 터미널을 계속 열어둘 필요가 없습니다.

xcode-copilot-server install-agent

이 명령은 ~/Library/LaunchAgents/에 plist 파일을 작성하고 launchctl로 이를 로드합니다. 에이전트는 지정된 포트에서 소켓 활성화가 설정되므로, launchd가 소켓을 소유하고 필요에 따라 서버를 시작합니다. 설정은 설치 시점에 패치됩니다.

install-agent 하위 명령은 메인 명령과 동일한 옵션 (--port, --proxy, --log-level, --config, --cwd)을 허용하며, 에이전트의 기본값이 60분인 --idle-timeout 옵션이 추가로 제공됩니다. 요청이 없는 상태로 60분이 지나면 서버는 스스로 종료됩니다. 다음 들어오는 연결이 서버를 다시 자동으로 시작합니다.

서버 로그는 ~/Library/Logs/xcode-copilot-server.out.log 및 ~/Library/Logs/xcode-copilot-server.err.log에 저장됩니다.

xcode-copilot-server uninstall-agent

이 명령은 에이전트 (agent)를 언로드(unload)하고, plist 파일을 삭제하며, 만약 에이전트가 --auto-patch 옵션과 함께 설치되었다면 패치된 모든 설정을 복구합니다.

launchd는 설정된 포트에서 소켓 (socket)을 생성하고 대기합니다. 연결이 들어오면 (예: Xcode가 요청을 보냄), launchd는 서버 프로세스를 시작하고 소켓을 넘겨줍니다. 서버는 평소와 같이 요청을 처리합니다.

서버가 충돌(crash)하더라도 launchd가 즉시 재시작하지는 않지만, 다음 연결이 들어올 때 새로운 프로세스가 시작됩니다. 만약 --idle-timeout이 설정되어 있다면 (에이전트의 경우 기본값은 60분), 서버는 해당 시간 동안 활동이 없을 경우 종료되며, launchd는 다음 연결 시 서버를 다시 시작합니다.

에이전트가 로드되었는지 확인하려면 다음 명령을 사용하세요:

launchctl list | grep xcode-copilot-server

xcode-copilot-server [options]
Options:
-p, --port <number> 대기할 포트 (기본값: 8080)
...

기본적으로 서버는 자동 모드 (auto mode)로 실행되며 모든 프로바이더 (provider)를 등록합니다. 대신 단일 프로바이더만 실행하려면 --proxy를 사용하세요:

프로바이더 (Provider)	플래그 (Flag)	경로 (Routes)
OpenAI	`--proxy openai`	`GET /v1/models` , `POST /v1/chat/completions`
Claude	`--proxy claude`	`POST /v1/messages` , `POST /v1/messages/count_tokens`
Codex	`--proxy codex`	`POST /v1/responses`

이 서버는 Xcode와 GitHub Copilot 사이에서 로컬 프록시 (local proxy) 역할을 합니다. 이 서버는 사용자의 로컬 머신에서 실행되며, 인터넷이나 공유 네트워크용으로 설계되지 않았습니다.

서버는 `127.0.0.1`에 바인딩(bind)되므로 사용자의 머신에서만 접근할 수 있습니다. 들어오는 요청은 예상되는 사용자 에이전트 (user-agent) 헤더를 확인합니다 (OpenAI 및 Codex의 경우 `Xcode/`, Claude의 경우 `claude-cli/`). 이는 다른 도구로부터의 일반적이거나 우발적인 연결은 거부됨을 의미합니다. 사용자 에이전트 헤더는 쉽게 위조(spoof)될 수 있으므로 강력한 보안 경계는 아니지만, 정상적인 사용 환경에서는 예상된 클라이언트만이 서버와 통신함을 의미합니다.

번들된 설정은 autoApprovePermissions를 ["read", "mcp"]로 설정합니다.

, 이는 Copilot 세션이 사용자에게 묻지 않고도 파일을 읽고 MCP 도구를 호출할 수 있게 합니다. 쓰기 (Writes), 셸 명령 (shell commands), URL 가져오기 (URL fetches)는 기본적으로 거부됩니다. 모든 것을 승인하려면 true로, 모든 것을 거부하려면 false로 설정하거나

본 소프트웨어는 상품성, 특정 목적에 대한 적합성 및 비침해성에 대한 보증을 포함하되 이에 국한되지 않고, 명시적이든 묵시적이든 어떠한 종류의 보증 없이 "있는 그대로" 제공됩니다. 어떠한 경우에도 저자 또는 저작권자는 계약상의 행위, 불법 행위 또는 기타 방식에 의한 소프트웨어와 관련하여 발생하거나, 소프트웨어의 사용 또는 기타 거래로 인해 발생하는 어떠한 청구, 손해 또는 기타 책임에 대해서도 책임을 지지 않습니다.