해외 개발자 커뮤니티에서 최근 'Claudex'라는 신조어가 유행하고 있습니다. 이는 공식 제품명은 아니지만, 개발자들이 "Claude Code의 인터페이스를 활용해 OpenAI 모델을 구동하는" 방식을 일컫는 별명입니다. 한 개발자가 소셜 미디어에 단 세 단계로 끝나는 설정 방법을 공유하며 "Codex 클라이언트를 따로 설치할 용기가 없다면, 익숙한 Claude Code 인터페이스에서 GPT-5.6 Sol을 사용해 보세요"라고 농담을 던진 것이 시작이었죠. 이 글은 Theo(t3.gg)가 기술적인 설명을 덧붙여 공유하면서 빠르게 확산되었고, 최근 AI 프로그래밍 도구 업계에서 가장 뜨거운 주제가 되었습니다. 이번 글에서는 Claudex의 의미와 그 기반이 되는 CLIProxyAPI 도구의 원리, 그리고 구체적인 설정 단계와 환경 변수를 하나씩 자세히 살펴보겠습니다.
Claudex란 무엇인가: 인터페이스와 모델의 결합
Claudex라는 이름은 Claude와 Codex의 합성어로, Claude Code의 명령줄 인터페이스와 도구 호출 메커니즘은 그대로 유지하면서 실제 추론 요청을 OpenAI의 GPT-5.6 Sol 모델로 전달하는 혼합 사용 방식을 의미합니다. 사람들이 이 조합을 시도하는 이유는 단순히 새로운 것을 원해서가 아닙니다. 커뮤니티 내의 비교 테스트 결과, GPT-5.6 Sol이 Claude Code의 작업 오케스트레이션 로직 하에서 구동될 때 Codex 네이티브 환경보다 더 안정적인 성능을 보였기 때문입니다.
문제는 Codex 공식 하네스(harness)의 알려진 결함 때문입니다. GitHub에 보고된 바에 따르면, GPT-5.6 Sol은 기본적으로 서브 에이전트 오케스트레이션 모드로 진입하는데, 이 모드에서 agent_type, model, reasoning_effort, service_tier와 같은 핵심 필드가 숨겨집니다. 이로 인해 Sol이 파생한 모든 하위 작업이 Sol 본연의 높은 비용 설정을 강제로 상속받게 되며, 더 가벼운 Terra나 Luna 모델을 사용할 수 있는 작업조차 다운그레이드가 불가능해집니다. 즉, Codex 환경의 서브 에이전트 라우팅 메커니즘 자체에 버그가 있는 반면, 파일 기반으로 서브 에이전트를 정의하는 Claude Code는 이러한 제한을 우회할 수 있습니다.
| 비교 항목 | Codex 네이티브 하네스 | Claude Code 하네스 (Claudex 모드) |
|---|---|---|
| 서브 에이전트 모델 다운그레이드 | 제한됨, Sol이 핵심 필드 숨김 | 환경 변수를 통해 명시적 지정 가능 |
| 서브 에이전트 정의 방식 | 내장 오케스트레이션 로직 | 파일 기반 subagent 정의 |
| 도구 호출 동시성 제어 | 고정 정책 | CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY로 조절 가능 |
| 도구 검색 메커니즘 | 기본 전체 로드 | ENABLE_TOOL_SEARCH로 필요에 따라 켜고 끄기 가능 |
다만, 일부 개발자들은 표준 코딩 작업에서는 눈에 띄는 성능 차이를 느끼지 못했다고 보고했습니다. 이러한 차이는 주로 복잡한 서브 에이전트 오케스트레이션이 필요한 작업에서 발생하는 것으로 보입니다. 따라서 Claudex는 무조건적인 최적의 해답이라기보다는 '하나의 선택지'로 활용할 수 있는 실험적인 설정으로 보는 것이 좋습니다.
이러한 설정 기법이 빠르게 퍼진 것은 놀라운 일이 아닙니다. GPT-5.6 시리즈 출시 이후 해외 개발자 커뮤니티에서는 "어떤 하네스가 Sol을 구동하기에 더 적합한가"에 대한 논의가 끊이지 않았습니다. 많은 이들이 이미 Claude Code의 상호작용 방식과 플러그인 생태계에 익숙해져 있으며, 새로운 모델을 사용하기 위해 완전히 낯선 도구 체인으로 전환하고 싶어 하지 않기 때문입니다. Claudex의 아이디어는 본질적으로 "최소한의 변경으로 최대의 이익을 얻는 것"입니다. 새로운 명령줄 도구를 새로 배울 필요 없이, 요청의 목적지만 바꾸는 방식이기에 단순히 Codex 클라이언트를 설치하는 것보다 훨씬 쉽게 받아들여지고 있습니다.
CLIProxyAPI란 무엇인가: 프로토콜 변환 프록시 계층
Claudex를 구현하려면 Claude Code에서 발생하는 Anthropic 프로토콜 요청을 OpenAI Codex가 이해할 수 있는 호출 형식으로 변환해 주는 중간 프록시 계층이 필수적입니다. 바로 이 역할을 수행하는 것이 CLIProxyAPI입니다. 이 오픈소스 로컬 프록시 서비스는 Codex, Claude Code, Gemini CLI 등 다양한 CLI 도구의 OAuth 세션을 OpenAI, Gemini, Claude, Codex 호환 HTTP API 인터페이스로 통합합니다. 또한 스트리밍 응답, 함수 호출, 멀티모달 입력 및 계정 간 로드 밸런싱까지 지원하죠.
이 서비스는 일종의 프로토콜 변환 게이트웨이와 같습니다. 모델 제조사마다 호출 로직을 따로 맞출 필요 없이, 프록시가 표준 인터페이스를 통합적으로 노출하는 방식입니다. 이는 APIYI(apiyi.com)의 접근 방식과 매우 유사합니다. 두 방식 모두 "모델별로 제각각인 인터페이스" 문제를 해결하지만, CLIProxyAPI는 사용자가 로컬에 보유한 Claude 및 ChatGPT 구독 계정을 활용하는 반면, APIYI와 같은 클라우드 게이트웨이는 API 키 하나로 GPT-5.6 전 시리즈 모델을 바로 호출하며 로컬에서 OAuth 세션이나 프록시 프로세스를 관리할 필요가 없다는 차이가 있습니다.
| 구성 요소 | 역할 | 호환 프로토콜 |
|---|---|---|
| OAuth 로그인 모듈 | 기존 Claude / ChatGPT 구독 정보 재사용 | Anthropic OAuth, OpenAI OAuth |
| 프로토콜 변환 계층 | 표준 인터페이스 통합 노출 | OpenAI / Gemini / Claude / Codex |
| 다중 계정 라우팅 | 요청 분산 처리로 단일 계정 제한 우회 | 전체 지원 |
| 로컬 서비스 프로세스 | CLI 도구 연결을 위한 로컬 포트 리스닝 | HTTP / WebSocket |
배포 형태를 보면, CLIProxyAPI는 바이너리 패키지와 Docker 이미지를 모두 제공합니다. 저장소에 포함된 docker-compose.yml과 빌드 스크립트를 사용하면 컨테이너화된 서비스를 바로 실행할 수 있습니다. 설정 파일은 YAML 형식이며, 리스닝 포트, 인증 정보 저장 경로, 다중 계정 라운드 로빈 활성화 여부 등을 정의합니다. 공식 저장소의 config.example.yaml을 복사해 본인의 환경에 맞게 수정하면 됩니다. 또한, 프록시 기능을 별도 프로세스가 아닌 내부 서비스에 직접 임베딩하고 싶다면 제공되는 Go SDK를 활용할 수도 있습니다.
5단계 설정 프로세스: 설치부터 실행까지
앞서 설명한 원리를 실전으로 옮기려면 다음 5단계를 따라 하세요. 첫째, CLIProxyAPI를 설치합니다. 공식 저장소의 바이너리나 Docker 이미지를 사용하고, YAML 설정 파일에 리스닝 포트와 인증 정보 경로를 지정합니다. 둘째, Claude와 OpenAI 계정으로 각각 OAuth 인증을 완료합니다. 프록시가 로컬에 두 인증 정보를 모두 저장하면, 이후 요청 시 모델에 맞춰 자동으로 적절한 계정을 선택합니다.
셋째, Claude Code의 요청 경로를 로컬 프록시로 돌립니다. 보통 ANTHROPIC_BASE_URL을 CLIProxyAPI 주소로 설정하면, Claude Code는 공식 Anthropic 인터페이스로 통신한다고 생각하지만 실제로는 프록시가 이를 가로채 전달하게 됩니다. 넷째, claudex 별칭 명령어를 생성하여 필요한 환경 변수를 포함시킵니다. 이제 명령어 하나로 혼합 모드를 실행할 수 있습니다. 다섯째, 복합적인 작업을 수행하여 테스트합니다. 단순한 파일 수정보다는 여러 하위 작업이 포함된 태스크를 실행해 라우팅이 제대로 작동하는지 확인하세요.
가장 주의할 점은 2단계와 3단계의 연결입니다. 두 계정의 OAuth 토큰은 갱신 주기가 다릅니다. 프록시 프로세스를 장시간 방치하면 토큰 만료로 인해 요청이 거부될 수 있는데, 이때 Claude Code가 오류 메시지 없이 멈추는 현상이 발생할 수 있습니다. 시스템 프로세스 관리 도구로 프록시를 관리하고, 정기적으로 로그를 확인해 계정 상태를 체크하는 것을 권장합니다.
# claudex 별칭 설정 예시
alias claudex='CLAUDE_CODE_SUBAGENT_MODEL=gpt-5.6-sol \
CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1 \
CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY=3 \
ENABLE_TOOL_SEARCH=false \
claude --model gpt-5.6-sol'
🎯 설정 팁: GPT-5.6 Sol의 성능을 먼저 경험해보고 싶다면, 굳이 복잡한 이중 OAuth 인증을 거칠 필요는 없습니다. APIYI(apiyi.com)에서 API 키를 발급받아 표준 OpenAI 호환 인터페이스로 GPT-5.6 Sol, Terra, Luna를 먼저 테스트해보세요. 충분히 검증한 뒤에 로컬 프록시 구축과 계정 관리 비용을 들일지 결정하는 것이 좋습니다.
claudex 별칭 내 환경 변수 상세 분석
위의 별칭(alias) 명령은 간단해 보이지만, 각각의 환경 변수는 서로 다른 문제를 해결합니다. 이 설정들이 본인의 작업 환경에 적합한지 판단하려면 각 변수의 역할을 이해하는 것이 중요해요.
| 환경 변수 | 역할 | 필요한 이유 |
|---|---|---|
CLAUDE_CODE_SUBAGENT_MODEL |
모든 하위 에이전트가 특정 모델을 사용하도록 강제 | Codex harness 숨김 필드로 인한 폴백 실패 문제 방지 |
CLAUDE_CODE_ALWAYS_ENABLE_EFFORT |
추론 강도 매개변수 항상 활성화 | Sol이 호출될 때마다 지정된 추론 수준 유지 |
CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY |
동시 도구 호출 수 제한 | 에이전트 전달 시 인터페이스 동시성 제한 오류 방지 |
ENABLE_TOOL_SEARCH |
온디맨드 도구 검색 메커니즘 비활성화 | 일부 에이전트 환경에서 도구 검색이 프로토콜 변환과 충돌 |
특히 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY 변수는 주의 깊게 살펴봐야 합니다. 에이전트 계층의 전달 속도가 Claude Code의 동시 도구 호출 요청을 따라가지 못하면 400 오류가 발생하기 쉽습니다. 이는 공식 API를 직접 호출할 때도 발생하는 문제로, 본질적으로는 동시 요청이 백엔드의 처리 능력을 초과했기 때문입니다. 이런 오류를 겪는다면 해당 환경 변수 값을 낮추는 것 외에도, 동시성 처리 능력이 더 뛰어난 APIYI와 같은 API 중계 서비스를 고려해 보세요. 불필요한 설정 디버깅 시간을 크게 줄일 수 있습니다.
일반적인 오류 해결: 지연부터 속도 제한까지
이 조합을 설정하는 과정에서 자주 발생하는 오류들이 있습니다. 미리 해결 방향을 알아두면 불필요한 시행착오를 줄일 수 있어요.
| 현상 | 가능한 원인 | 해결 방향 |
|---|---|---|
| Claude Code 응답 없음 | 프록시 프로세스 OAuth 토큰 만료 | 프록시 로그 확인 후 로그인 절차 재수행 |
| 400 오류 및 동시성 초과 알림 | 도구 호출 동시성이 백엔드 처리 능력 초과 | CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY 값 낮추기 |
| 하위 에이전트가 여전히 고비용 모델 사용 | 환경 변수가 현재 셸에 적용되지 않음 | Claude Code를 실행하는 동일 세션에서 별칭 정의 확인 |
| 도구 목록 로딩이 매우 느림 | 도구 검색 메커니즘과 프로토콜 변환 충돌 | ENABLE_TOOL_SEARCH 설정 변경 시도 |
그중 동시성 제한 오류는 가장 흔한 문제입니다. 이는 공식 API를 직접 호출할 때 발생하는 제한과 근본적으로 같은 원인으로, 요청 속도가 백엔드의 처리 능력을 넘어서기 때문입니다. 로컬 프록시를 사용하든 클라우드 인터페이스를 직접 호출하든, 먼저 동시성을 낮춘 뒤 점진적으로 한계치를 테스트하는 방식이 문제의 원인을 파악하는 데 훨씬 효과적입니다.
GPT-5.6 시리즈 모델, 무엇을 선택해야 할까요?
Claudex 설정에서는 기본적으로 GPT-5.6 Sol을 가리키고 있지만, 이는 GPT-5.6 제품군 중 가장 높은 등급일 뿐입니다. 이 명명 체계는 숫자로 모델 세대를 구분하고, Sol, Terra, Luna라는 명칭으로 독립적인 반복이 가능한 세 가지 능력 계층을 나타내며, 각각 다른 작업 복잡도와 비용 예산에 대응합니다.
| 모델 | 포지셔닝 | 적합한 시나리오 |
|---|---|---|
| GPT-5.6 Sol | 복잡한 추론 및 긴 링크 작업용 플래그십 | 다중 하위 에이전트 오케스트레이션, 연구급 분석, 보안 감사 |
| GPT-5.6 Terra | 일상적인 주력 모델 | 일반적인 코딩, 문서 처리, 배치 작업 |
| GPT-5.6 Luna | 경량형 고빈도 모델 | 단순 반복 작업, 빠른 응답이 필요한 시나리오 |
Claudex의 하위 에이전트 라우팅 솔루션을 활용하는 핵심은 복잡한 메인 작업은 Sol이 처리하게 하고, 분할된 경량 하위 작업은 자동으로 Terra나 Luna로 강등시켜 전체 모델 호출 비용을 제어하는 데 있습니다. 로컬 에이전트를 직접 유지 관리하고 싶지 않다면 APIYI(apiyi.com) 플랫폼을 통해 필요에 따라 이 세 가지 모델을 호출할 수 있습니다. 동일한 계정 체계로 작업 계획부터 하위 작업 실행까지 모든 호출을 완료할 수 있으며, 하위 에이전트 라우팅이 harness에 의해 제한되는지 신경 쓸 필요가 없습니다.
모델을 선택할 때 "무조건 가장 비싼 것을 써야 한다"고 고민할 필요는 없습니다. Sol의 가격은 Terra나 Luna보다 훨씬 높기 때문에, 작업 자체가 깊은 추론이나 긴 링크 오케스트레이션을 포함하지 않는다면 Terra만으로도 비슷한 결과를 얻으면서 비용을 크게 절감할 수 있습니다. 이것이 바로 단순히 모델 하나를 고르는 것보다 하위 에이전트 강등 메커니즘을 이해하는 것이 더 중요한 이유입니다. 전체 비용을 결정하는 것은 메인 작업에 어떤 모델을 썼느냐가 아니라, 분할된 수많은 하위 작업이 저렴한 등급으로 적절히 배분되었는지 여부이기 때문입니다.
자주 묻는 질문 (FAQ)
Claudex는 Anthropic이나 OpenAI에서 공식 출시한 제품인가요?
아닙니다. 이는 개발자 커뮤니티에서 CLIProxyAPI와 같은 타사 프록시 도구를 기반으로 구축한 혼합 사용 방식입니다. 본질적으로 두 업체의 인터페이스와 모델 기능을 결합한 것이며, 어느 쪽의 공식 입장도 대변하지 않습니다.
왜 Codex 클라이언트로 직접 GPT-5.6 Sol을 호출하지 않나요?
직접 호출할 수도 있지만, 일부 개발자들은 Codex의 기본 harness가 하위 에이전트 오케스트레이션 시나리오에서 라우팅 결함이 있어 경량 하위 작업이 더 저렴한 모델로 강등되지 않는다는 피드백을 주고 있습니다. 복잡한 하위 에이전트 분할이 포함되지 않는 작업이라면 이 차이를 크게 느끼지 못할 수도 있습니다.
CLIProxyAPI 프록시를 구축하는 데 보안 위험은 없나요?
로컬 프록시는 사용자의 계정 OAuth 인증 정보를 저장하므로, 구성 파일의 접근 권한에 주의해야 하며 공개적으로 접근 가능한 서버에 배포하지 않도록 해야 합니다. 단순히 모델 성능을 빠르게 검증하고 싶다면 APIYI(apiyi.com)와 같은 클라우드 게이트웨이를 독립적인 API 키와 함께 사용하는 것이 접근 제어 및 사용량 감사에 훨씬 유리합니다.
팀 내 여러 명이 이 설정을 공유하려면 어떻게 해야 하나요?
CLIProxyAPI는 다중 계정 순환을 지원하므로 이론적으로는 팀원들의 구독 계정을 하나의 프록시 인스턴스에 연결하여 요청을 분산할 수 있습니다. 하지만 이 방식은 인증 정보 관리의 복잡도를 배로 증가시키며, 특정 계정에 문제가 생기면 팀 전체의 호출이 영향을 받게 됩니다. 팀 단위 환경에서는 통합 API 게이트웨이를 통해 팀원별로 독립적인 키를 할당하는 것을 권장합니다. 이렇게 하면 문제가 발생했을 때 모든 사람이 하나의 로컬 프록시 프로세스를 공유하는 것보다 훨씬 정확하게 호출 주체를 파악할 수 있습니다.
마무리하며
Claudex는 결국 커뮤니티가 자발적으로 탐색해 낸 엔지니어링 우회 전략입니다. 이 방식의 가치는 특정 모델이나 도구의 절대적인 우위를 증명하는 것이 아니라, 각 제조사의 하네스(harness)가 서브 에이전트 오케스트레이션에서 어떤 구현 차이를 보이는지를 드러냈다는 점에 있습니다. 개발자들이 자발적으로 조합해 만든 이러한 방식은 수명이 길지 않은 경우가 많습니다. Codex 공식 측에서 서브 에이전트 라우팅의 필드 숨김 문제를 해결하는 순간, Claudex가 존재해야 할 이유도 사라질 것입니다. 하지만 "하네스 설계가 모델 성능에 실질적인 영향을 미친다"는 통찰은 향후 어떤 AI 프로그래밍 도구를 평가하더라도 여전히 유효한 참고 자료가 될 것입니다. 만약 GPT-5.6 Sol의 추론 능력을 단순히 경험해보고 싶은 정도라면, 굳이 지금 바로 시간을 들여 CLIProxyAPI를 구축하고 복잡한 이중 OAuth 로그인을 처리할 필요는 없습니다. 먼저 APIYI(apiyi.com)를 통해 표준 인터페이스로 결과를 확인해 본 뒤, 충분한 가치가 있다고 판단될 때 로컬 프록시 경로를 깊게 파고드는 것을 추천합니다.
