Claude에서 Codex 사용하기, 일명 "claudex" 설정 가이드
익숙한 Claude Code 화면과 도구는 그대로, 실제 추론은 Codex 모델로. 별칭 뒤에 숨은 프록시 구조부터 설치·보안·문제 해결까지 한 번에 정리했습니다.
안녕하세요, SCV입니다.
Claude Code의 익숙한 터미널 화면과 도구를 그대로 쓰면서, 실제 응답 모델은 OpenAI의 Codex 계열로 바꿀 수 있을까. 2026년 7월 12일 Theo가 X에 공개한 ‘claudex’는 이 아이디어를 짧은 셸 별칭으로 구현한 비공식 조합이다. 화면은 Claude Code지만 모델 표시에는 GPT-5.6 Sol이 나타난다. 이름도 Claude와 Codex를 합쳐 claudex다.
다만 별칭 한 줄만 복사한다고 바로 동작하는 것은 아니다. Claude Code가 보내는 Anthropic 형식 요청을 Codex 쪽으로 전달하고 응답을 다시 맞춰 주는 호환 프록시가 먼저 준비되어야 한다. 원문에서는 CLIProxyAPI를 설치하고 Codex 인증을 연결한 다음, Claude Code가 그 프록시를 바라보도록 설정했다고 설명한다. 이 글은 원문의 짧은 설명을 실제로 따라 할 수 있는 순서로 풀고, 환경 변수의 역할과 실패 지점, 보안상 주의할 점까지 함께 정리한다.
먼저 결론: claudex는 새로운 앱이 아니다
claudex는 별도의 AI 코딩 도구나 공식 제품명이 아니다. zsh 설정 파일에 등록한 alias 이름일 뿐이다. 사용자가 터미널에서 claudex를 입력하면 내부적으로 claude 명령이 실행되고, 실행 직전에 몇 개의 환경 변수가 임시로 주입된다. Claude Code가 사용자 인터페이스, 파일 읽기와 수정, 셸 실행, 서브에이전트 같은 ‘에이전트 하네스’를 담당하고, 실제 추론 모델은 호환 프록시가 지정한 GPT-5.6 Sol로 라우팅하는 구조다.
쉽게 말하면 운전석과 계기판은 Claude Code이고 엔진은 Codex 모델인 셈이다. Claude Code의 명령 체계와 권한 승인 화면, CLAUDE.md 규칙, 플러그인과 도구 사용 흐름은 남지만, 답변의 성향과 코딩 능력은 연결된 모델의 영향을 받는다. 반대로 Codex 앱이나 Codex CLI의 고유 인터페이스, AGENTS.md 처리 방식, 샌드박스 구현이 그대로 이식되는 것은 아니다. ‘Claude Code 안에서 Codex를 쓴다’는 말은 모델 라우팅을 뜻하지 두 제품 전체를 합친다는 뜻은 아니다.
전체 구성은 3단계다
첫째, CLIProxyAPI를 설치하고 로컬 서버를 실행한다. 이 프로젝트는 OpenAI, Gemini, Claude, Codex 형식 사이를 중계하는 오픈소스 프록시다. 기본 예시는 127.0.0.1의 8317 포트를 사용한다. 외부 네트워크에 공개할 이유가 없다면 반드시 로컬 호스트에만 바인딩하는 편이 안전하다.
둘째, CLIProxyAPI에서 Codex OAuth 로그인을 진행한다. 프로젝트 문서의 실행 파일 기준 명령은 ./cli-proxy-api --codex-login이며, Docker 환경은 별도의 콜백 포트 매핑이 필요하다. 브라우저 인증이 완료되면 토큰이 인증 디렉터리에 저장된다. 이 토큰은 비밀번호와 같은 민감 정보이므로 Git 저장소, 캡처 이미지, 블로그 글에 포함하면 안 된다.
셋째, Claude Code의 ANTHROPIC_BASE_URL과 ANTHROPIC_AUTH_TOKEN을 프록시 주소와 클라이언트 키로 설정한다. 이후 claudex 별칭을 등록하면 된다. 원문 캡처의 ~/.claude/settings.json에는 프록시 주소와 인증 토큰이 이미 들어 있었기 때문에 별칭이 짧아 보였던 것이다. 즉 별칭은 마지막 스위치이고, 실제 연결을 만드는 부분은 프록시와 Claude Code 설정이다.
1단계: CLIProxyAPI 설치와 Codex 인증
macOS에서는 프로젝트의 빠른 시작 문서가 Homebrew 설치를 안내한다. 설치 방법은 릴리스에 따라 바뀔 수 있으므로 실행 전 공식 문서를 다시 확인하는 것이 좋다. 아래 명령은 2026년 7월 14일 확인한 문서 기준이다.
brew install cliproxyapi
brew services start cliproxyapiHomebrew 서비스로 실행하면 설정 파일 위치가 일반적인 ~/.cli-proxy-api/config.yaml과 다를 수 있다. Apple Silicon은 보통 /opt/homebrew/etc/cliproxyapi.conf, Intel Mac은 /usr/local/etc/cliproxyapi.conf를 읽는다. 이미 사용자 폴더에 설정 파일을 만들었다면 공식 문서의 심볼릭 링크 절차를 따르거나 서비스가 실제로 읽는 파일을 수정해야 한다. 설정을 바꿨는데 아무 변화가 없을 때 가장 먼저 확인할 부분이다.
기본 설정에서는 포트 8317을 사용한다. host를 127.0.0.1로 제한하고, Claude Code가 접속할 api-keys 값을 별도로 만든다. 관리 화면용 secret-key와 클라이언트 접속용 api-keys는 역할이 다르다. 두 값을 혼동하거나 인터넷에 노출하지 말아야 한다.
host: "127.0.0.1"
port: 8317
remote-management:
allow-remote: false
secret-key: ""
auth-dir: "~/.cli-proxy-api"
api-keys:
- "REPLACE_WITH_A_LONG_RANDOM_CLIENT_KEY"설치 후에는 Codex 로그인 흐름을 실행한다. 직접 내려받은 바이너리 이름은 운영체제와 설치 방식에 따라 다를 수 있다. Homebrew 서비스가 이미 실행 중이라면 관리 화면에서 OAuth를 연결하는 방법도 있다. 핵심은 CLIProxyAPI의 인증 디렉터리에 Codex 자격 증명이 정상 저장되고, 서버가 127.0.0.1:8317에서 응답하는 상태를 만드는 것이다.
# Homebrew 설치 예시
cliproxyapi --codex-login
# 직접 받은 실행 파일 예시
./cli-proxy-api --codex-login2단계: Claude Code를 프록시에 연결하기
Claude Code 공식 문서는 ANTHROPIC_BASE_URL을 프록시나 게이트웨이로 요청을 우회하는 공식 환경 변수로 설명한다. ANTHROPIC_AUTH_TOKEN은 Authorization 헤더에 Bearer 방식으로 붙는 값이다. CLIProxyAPI 기본 예시는 sk-dummy를 쓰기도 하지만, 실제 사용에서는 config에 직접 만든 충분히 긴 키를 넣는 편이 낫다.
사용자 전체 프로젝트에 적용하려면 ~/.claude/settings.json의 env 항목을 사용할 수 있다. 특정 프로젝트에서만 시험하려면 .claude/settings.local.json을 만들고 Git에서 제외하는 쪽이 안전하다. 팀 저장소에 체크인되는 .claude/settings.json에 실제 토큰을 넣으면 안 된다.
{
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:8317",
"ANTHROPIC_AUTH_TOKEN": "REPLACE_WITH_YOUR_CLIENT_KEY"
}
}여기서 주소 끝에는 /v1을 붙이지 않는 예시가 일반적이다. Claude Code는 Anthropic 호환 엔드포인트를 사용하고, CLIProxyAPI의 Codex 클라이언트 설정과는 경로가 다를 수 있다. 404 오류가 난다면 프록시 프로세스, 포트, base URL 경로를 차례로 확인한다.
Claude Code 공식 문서는 타사 게이트웨이를 통한 비 Claude 모델 라우팅을 Anthropic이 지원하거나 보증하지 않는다고 명시한다. Claude Code가 업데이트되면서 새로운 요청 필드나 베타 헤더가 추가되면 프록시가 이를 이해하지 못해 갑자기 오류가 날 수 있다. 따라서 Claude Code와 CLIProxyAPI를 동시에 최신으로 올리기보다, 동작하는 버전을 기록하고 한쪽씩 업데이트하는 편이 문제를 찾기 쉽다.
3단계: 복사 가능한 claudex 별칭
이제 요청한 핵심 명령어다. zsh를 사용한다면 아래 블록을 ~/.zshrc에 붙여 넣고 새 터미널을 열거나 source ~/.zshrc를 실행한다. bash라면 ~/.bashrc 또는 ~/.bash_profile에 넣는다.
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'등록 후 claudex를 입력하면 Claude Code가 GPT-5.6 Sol 모델 이름으로 시작된다. claudex --continue, claudex --resume처럼 뒤에 붙인 인자도 일반적인 alias 확장에서는 claude 명령 뒤로 전달된다. 원문 화면처럼 상단에 모델 이름과 effort 상태가 표시되는지 확인한다.
이 별칭에는 ANTHROPIC_BASE_URL과 ANTHROPIC_AUTH_TOKEN이 없다. 두 값은 앞 단계의 ~/.claude/settings.json에 이미 설정되어 있다는 전제다. 설정 파일을 사용하지 않고 별칭 하나에 모두 넣고 싶다면 두 환경 변수를 앞에 추가할 수 있지만, 토큰이 셸 기록이나 화면 공유에 노출될 가능성이 커진다. 토큰은 별도 비밀 저장소나 사용자 전용 설정에 두는 것이 낫다.
환경 변수 4개의 정확한 역할
CLAUDE_CODE_SUBAGENT_MODEL=gpt-5.6-sol은 Claude Code가 생성하는 서브에이전트도 같은 모델을 사용하도록 지정한다. 이 값이 없으면 메인 대화와 서브에이전트가 서로 다른 모델로 처리될 수 있다. Claude Code 공식 환경 변수 목록에 등재된 항목이며, 버전에 따라 inherit 동작이 달라졌으므로 버전 차이를 의식해야 한다.
CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1은 Claude Code가 해당 모델 이름을 기본 지원 모델로 인식하지 못하더라도 effort 파라미터를 보내도록 한다. 공식 문서도 LLM 게이트웨이나 사용자 정의 모델 식별자를 라우팅할 때 쓰는 옵션으로 설명한다. 다만 프록시 또는 모델이 effort 필드를 받지 못하면 요청 오류가 날 수 있다.
CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY=3은 원문 설정에서 동시 도구 호출을 3개로 제한하려는 의도다. 그러나 2026년 7월 14일 기준 Claude Code 공식 환경 변수 목록에서는 이 정확한 이름을 찾을 수 없었다. 내부 또는 버전 한정 옵션일 가능성이 있으므로 항상 효과가 있다고 단정하면 안 된다. 실제 동시성은 Claude Code 버전, 프록시, 모델의 도구 호출 구현에 따라 달라질 수 있다.
ENABLE_TOOL_SEARCH=false는 MCP 도구를 지연 검색하지 않고 처음부터 로드하도록 한다. Claude Code 공식 문서에서 false는 모든 도구를 upfront 방식으로 로드하는 값이다. 타사 프록시가 tool_reference 블록을 지원하지 않을 때 호환성을 높일 수 있지만, 연결된 MCP 도구가 많으면 초기 컨텍스트 사용량이 늘어난다.
| 환경 변수 | 의도 | 확인 상태 |
|---|---|---|
CLAUDE_CODE_SUBAGENT_MODEL | 서브에이전트 모델 지정 | 공식 문서 등재 |
CLAUDE_CODE_ALWAYS_ENABLE_EFFORT | 사용자 정의 모델에도 effort 전송 | 공식 문서 등재 |
CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY | 도구 동시 호출을 3개로 제한하려는 설정 | 공식 목록 미확인 |
ENABLE_TOOL_SEARCH | MCP 도구 지연 검색 비활성화 | 공식 문서 등재 |
이 조합에서 유지되는 것과 달라지는 것
유지되는 것은 Claude Code의 터미널 UI, 프로젝트 탐색, 파일 편집, 셸 도구, 권한 승인, 훅과 플러그인, CLAUDE.md 중심의 지침 로딩이다. 사용자는 평소 Claude Code를 쓰던 방식으로 작업할 수 있다. 특히 이미 Claude Code 단축키와 플러그인 환경에 익숙하지만 Codex 모델의 결과를 비교하고 싶은 사람에게 유용하다.
달라지는 것은 모델의 추론 방식, 도구 호출 포맷을 생성하는 성향, 답변 문체, 컨텍스트 처리 특성이다. 프록시가 요청과 응답을 번역하므로 네이티브 Codex CLI와 완전히 같은 결과를 기대하면 안 된다. Codex CLI 전용 기능이나 최신 Responses API 필드가 Claude Code의 Anthropic 형식으로 완벽하게 표현되지 않을 수도 있다.
또한 장애 지점이 하나 늘어난다. 일반 Claude Code는 클라이언트와 Anthropic 사이를 연결하지만 claudex는 Claude Code, CLIProxyAPI, Codex 인증, OpenAI 서비스까지 이어진다. 어느 한 단계의 버전이나 인증이 바뀌어도 전체가 멈출 수 있다. 실험용으로는 흥미롭지만, 업무 핵심 경로라면 네이티브 도구를 함께 남겨 두는 것이 좋다.
| 구분 | claudex 구성 | 네이티브 Codex |
|---|---|---|
| 화면과 도구 | Claude Code | Codex 앱·CLI |
| 주요 규칙 파일 | CLAUDE.md 중심 | AGENTS.md 중심 |
| 모델 연결 | CLIProxyAPI 형식 변환 | OpenAI 네이티브 연결 |
| 장점 | 익숙한 Claude Code 작업 흐름 유지 | 지원 경계와 기능 호환성이 명확 |
| 부담 | 프록시 보안·버전·인증 관리 | 별도 UI와 설정에 적응 |
실행 확인과 문제 해결 순서
첫 확인은 프록시다. 브라우저 관리 화면이나 서버 로그에서 CLIProxyAPI가 8317 포트를 듣고 있는지 확인한다. 연결 거부가 나오면 alias를 고칠 것이 아니라 프록시 프로세스와 방화벽부터 본다.
두 번째는 인증이다. 401 또는 403이면 Claude Code가 보내는 ANTHROPIC_AUTH_TOKEN과 CLIProxyAPI의 api-keys가 일치하는지 확인한다. Codex OAuth가 만료되었거나 인증 파일이 손상된 경우에는 Codex 로그인을 다시 진행한다. 실제 토큰 값을 로그나 질문 글에 붙여 넣지 말고 오류 코드와 마스킹한 설정만 공유한다.
세 번째는 모델 이름이다. 모델을 찾을 수 없다는 오류가 나오면 CLIProxyAPI가 gpt-5.6-sol이라는 별칭을 현재 지원하는지 확인한다. 원문이 게시된 시점의 모델명은 미래 릴리스나 프록시 설정에 따라 바뀔 수 있다. 서버의 모델 목록에 없는 이름을 claude --model에 넣어도 자동으로 생기지 않는다.
네 번째는 요청 호환성이다. 400 오류와 함께 beta header, thinking, tool_reference 같은 단어가 보이면 Claude Code가 보낸 필드를 프록시가 처리하지 못한 것이다. 이때 무작정 권한을 완화하지 말고 CLIProxyAPI를 업데이트하거나 Claude Code 버전을 되돌린다. 공식 문서에는 일부 게이트웨이를 위한 호환성 환경 변수도 있지만, 오류 메시지와 문서를 확인한 뒤 필요한 옵션만 추가해야 한다.
다섯 번째는 별칭 해석이다. type claudex 또는 alias claudex를 실행해 현재 셸이 어떤 정의를 사용하는지 확인한다. 같은 이름의 실행 파일이 ~/.local/bin에 있어도 셸 alias가 우선할 수 있다. 수정 후 source ~/.zshrc를 하지 않아 이전 정의가 남아 있는 경우도 흔하다.
127.0.0.1:8317에서 실행 중인지 확인gpt-5.6-sol을 노출하는지 확인type claudex로 실제 alias 정의 확인보안과 이용 조건에서 꼭 알아둘 점
CLIProxyAPI는 서드파티 오픈소스 프로젝트다. Anthropic 공식 문서는 제3자 게이트웨이를 보증하거나 감사하지 않으며, 비 Claude 모델 라우팅을 지원하지 않는다고 밝힌다. 프록시는 프롬프트, 코드 조각, 도구 결과, 인증 토큰이 지나는 매우 민감한 위치다. 개인 컴퓨터에서 소스와 릴리스를 확인하고, 127.0.0.1에만 바인딩하고, 원격 관리 기능은 필요할 때만 켜야 한다.
OAuth 토큰이나 구독 인증을 다른 클라이언트로 중계하는 방식은 공급자의 약관과 조직 정책에 영향을 받을 수 있다. ‘구독이 있으니 어떤 도구에서든 무제한으로 써도 된다’고 가정해서는 안 된다. 회사 코드, 고객 데이터, 비공개 저장소를 다룬다면 보안 담당자의 승인과 데이터 처리 정책을 먼저 확인한다.
권한 우회 모드도 별개의 위험이다. 원문 화면 하단에는 bypass permissions가 켜져 있지만 claudex를 위해 반드시 필요한 설정은 아니다. 모델을 바꾸는 것과 파일 삭제·셸 실행 승인을 생략하는 것은 전혀 다른 문제다. 처음 테스트할 때는 기본 승인 정책과 샌드박스를 유지하고, 빈 테스트 저장소에서 읽기·수정·테스트 흐름을 검증하는 것이 안전하다.
누구에게 추천하고 누구에게는 비추천할까
Claude Code의 UI와 플러그인 생태계를 좋아하면서 모델별 결과를 비교하려는 개발자, 로컬 게이트웨이와 API 형식 변환을 이해하는 사용자, 문제가 생겼을 때 로그를 읽고 버전을 고정할 수 있는 사람에게는 재미있는 실험이다. 같은 작업을 Claude 모델과 Codex 모델에 번갈아 맡겨 코드 리뷰 관점이나 구현 스타일을 비교하는 용도로 특히 적합하다.
반대로 설치 후 유지보수에 시간을 쓰고 싶지 않은 사람, 회사의 민감한 저장소를 다루는 사람, OAuth와 프록시의 보안 범위를 검토하기 어려운 사람에게는 추천하기 어렵다. 이 경우에는 Codex 앱 또는 Codex CLI를 네이티브로 쓰는 편이 단순하고 지원 경계도 명확하다.
정리하면 claudex의 매력은 Claude Code라는 익숙한 작업대에 Codex 모델을 얹는 데 있다. 하지만 실제 핵심은 멋진 alias가 아니라 Anthropic 호환 요청을 Codex로 안전하게 전달하는 게이트웨이다. 프록시를 먼저 설치하고 인증과 base URL을 검증한 뒤 마지막에 alias를 추가해야 한다. 이 순서를 지키면 오류가 생겨도 어느 계층에서 막혔는지 훨씬 빠르게 찾을 수 있다.
Windows PowerShell에서 같은 명령 만들기
원문의 alias 문법은 zsh와 bash용이므로 Windows PowerShell에 그대로 붙이면 실행되지 않는다. PowerShell의 Alias 기능은 단순히 명령 이름만 다른 이름에 연결하며, 여러 환경 변수를 설정한 뒤 인자를 전달하는 복합 동작에는 적합하지 않다. 이 경우에는 함수를 만들어 $PROFILE에 저장하는 편이 자연스럽다.
아래 함수는 현재 세션에 들어 있던 4개 환경 변수 값을 먼저 보관하고, Claude Code를 실행하는 동안에만 claudex 값을 적용한 뒤, 프로그램이 끝나면 원래 값으로 되돌린다. @args를 사용하므로 claudex --continue처럼 추가한 인자도 claude 명령으로 전달된다. base URL과 인증 토큰은 zsh 예시와 마찬가지로 Claude Code 설정 파일에 들어 있다는 전제다.
function claudex {
$names = @(
'CLAUDE_CODE_SUBAGENT_MODEL',
'CLAUDE_CODE_ALWAYS_ENABLE_EFFORT',
'CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY',
'ENABLE_TOOL_SEARCH'
)
$old = @{}
foreach ($name in $names) { $old[$name] = [Environment]::GetEnvironmentVariable($name, 'Process') }
try {
$env:CLAUDE_CODE_SUBAGENT_MODEL = 'gpt-5.6-sol'
$env:CLAUDE_CODE_ALWAYS_ENABLE_EFFORT = '1'
$env:CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY = '3'
$env:ENABLE_TOOL_SEARCH = 'false'
& claude --model gpt-5.6-sol @args
}
finally {
foreach ($name in $names) { [Environment]::SetEnvironmentVariable($name, $old[$name], 'Process') }
}
}메모장 $PROFILE 또는 code $PROFILE로 프로필을 연 뒤 함수를 추가하고 새 PowerShell 창을 열면 된다. 프로필 파일이 없다는 오류가 나오면 New-Item -ItemType File -Path $PROFILE -Force로 만든다. 회사 PC에서 실행 정책이 프로필 로딩을 막는다면 정책을 임의로 낮추지 말고 관리자 지침을 확인한다. WSL을 사용 중이라면 PowerShell 함수 대신 앞의 bash 또는 zsh alias를 적용하는 편이 간단하다.
PowerShell 버전에서도 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY의 효과가 보장되는 것은 아니다. 함수의 장점은 설정을 영구 환경 변수로 남기지 않는 데 있다. 다만 Claude Code가 비정상 종료되거나 터미널 자체가 강제 종료되면 finally 블록이 완전히 실행되지 않을 가능성이 있으므로, 새 터미널에서 환경을 다시 확인하면 된다.
오래 쓰려면 버전과 검증 결과를 기록하자
claudex는 최소 3개 소프트웨어의 움직이는 경계 위에 있다. Claude Code가 요청 스키마를 바꾸고, CLIProxyAPI가 번역 규칙을 업데이트하며, Codex 모델 이름이나 인증 방식도 달라질 수 있다. 오늘 성공한 설정이 다음 달에도 같은 명령으로 동작한다고 장담할 수 없다. 그래서 한 번 연결한 뒤에는 Claude Code 버전, CLIProxyAPI 버전, 사용한 모델명, 설정 파일 위치, 성공한 날짜를 짧은 메모로 남기는 것이 좋다.
업데이트도 한꺼번에 하지 않는다. 먼저 빈 저장소에서 현재 조합의 읽기, 수정, 테스트, 서브에이전트 호출을 확인하고 결과를 적는다. 그다음 Claude Code 또는 CLIProxyAPI 중 하나만 업데이트한 뒤 같은 검사를 반복한다. 문제가 생겼을 때 변경된 계층이 하나뿐이면 원인을 찾거나 이전 버전으로 돌아가기가 훨씬 쉽다.
모델이 정말 바뀌었는지도 화면의 이름만 보고 판단하지 않는다. 프록시 로그에서 실제 라우팅 모델을 확인하고, 민감한 프롬프트나 토큰은 마스킹한다. 가능하다면 동일한 작은 코딩 과제를 네이티브 Codex와 claudex에 각각 실행해 도구 호출, 수정 결과, 테스트 통과 여부를 비교한다. Claude Code 화면에 사용자 지정 문자열이 표시되는 것과 실제 상류 모델이 그 이름대로 처리되는 것은 서로 다른 검증 문제다.
업무에 도입한다면 실패 시 대체 경로도 정한다. claudex가 멈췄을 때 기본 claude 명령이나 네이티브 codex 명령으로 바로 전환할 수 있어야 한다. 프록시 설정을 기존 Claude Code 설정과 분리해 두면 복구가 쉽다. 예를 들어 특정 프로젝트의 .claude/settings.local.json에서만 시험하거나, 별도 CLAUDE_CONFIG_DIR를 사용하는 방식으로 실험 환경을 격리할 수 있다.
마지막으로 로그 보존 범위를 확인한다. 디버그 로그에는 요청 본문과 코드가 포함될 수 있고, 장시간 켜 두면 저장 공간도 빠르게 늘어난다. 평상시에는 debug와 상세 요청 로그를 끄고, 장애 분석 때만 잠깐 활성화한 다음 민감 정보를 제거해 공유한다. 모델을 바꾸는 실험보다 중요한 것은 코드와 인증 정보가 어디를 통과하고 어디에 남는지 아는 것이다.
처음 연결했을 때는 큰 프로젝트를 맡기기보다 5분짜리 점검 과제를 사용한다. 새 폴더에 간단한 계산 함수와 실패하는 테스트 1개를 만들고, claudex에게 원인을 설명한 뒤 최소 수정으로 통과시키라고 요청한다. 이 과정에서 파일 읽기, 변경 제안, 실제 쓰기, 셸 테스트 실행, 결과 요약이 모두 정상인지 볼 수 있다. 다음에는 같은 저장소를 읽기 전용으로 분석하게 해 승인 화면이 예상대로 나타나는지 확인한다.
서브에이전트 설정을 검증하려면 작은 조사 작업을 2개로 나누어 맡기고, 프록시 로그에서 각 요청의 모델명을 확인한다. 메인 화면에만 GPT-5.6 Sol이 표시되고 서브에이전트는 다른 모델로 라우팅될 수도 있기 때문이다. 동시 호출 제한을 확인하고 싶다면 시간대가 겹치는 도구 호출 수를 로그로 관찰한다. 환경 변수 이름을 넣었다는 사실보다 실제 요청 패턴이 원하는 대로 변했는지가 중요하다.
성공 기준도 미리 적는다. 예를 들어 파일 범위를 벗어나지 않음, 승인 없이 위험 명령을 실행하지 않음, 테스트를 1회 이상 실행함, 변경 파일을 정확히 요약함, 오류가 나면 재시도 전에 원인을 설명함 같은 항목이다. 모델의 답변이 그럴듯한지만 보면 프록시와 권한 계층의 문제를 놓치기 쉽다. 실행 결과와 안전 동작을 함께 확인해야 비로소 재현 가능한 설정이라고 할 수 있다.
이 점검 기록은 다음 업데이트에서 회귀 여부를 판단하는 가장 간단하고 확실한 기준이 된다.
자주 묻는 질문
Q1. alias 한 줄만 복사하면 바로 사용할 수 있나요?+
아니다. CLIProxyAPI 같은 호환 프록시가 실행 중이어야 하고, Codex 인증과 Claude Code의 ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN 설정이 먼저 끝나야 한다. alias는 이미 준비된 연결을 짧게 실행하는 마지막 단계다.
Q2. Claude 구독과 ChatGPT 구독 중 어느 쪽 사용량이 차감되나요?+
이 구성에서는 Claude Code 화면을 사용하더라도 실제 모델 요청은 프록시가 연결한 Codex 인증 쪽으로 라우팅된다. 정확한 과금과 한도는 사용한 CLIProxyAPI 인증 방식과 공급자 정책에 따라 달라지므로 각 계정의 사용량 화면에서 확인해야 한다.
Q3. gpt-5.6-sol 대신 다른 모델명을 넣어도 되나요?+
프록시가 그 모델 또는 별칭을 노출하고 Claude 호환 형식으로 변환할 수 있다면 가능하다. 먼저 CLIProxyAPI의 지원 모델 목록을 확인해야 하며, 존재하지 않는 이름을 alias에 적는 것만으로 모델이 추가되지는 않는다.
Q4. Windows PowerShell에서도 같은 alias를 쓸 수 있나요?+
문법이 다르다. 여기의 alias는 zsh와 bash 같은 POSIX 셸용이다. PowerShell에서는 함수 안에서 환경 변수를 임시 설정하고 claude를 호출한 뒤 원래 값을 복원하는 방식이 필요하다. WSL을 사용하면 글의 zsh 또는 bash 예시를 거의 그대로 적용할 수 있다.
Q5. 이 방법은 Anthropic이나 OpenAI가 공식 지원하나요?+
아니다. Claude Code는 ANTHROPIC_BASE_URL을 통한 게이트웨이 연결 자체는 공식 문서화하지만, Anthropic은 제3자 게이트웨이를 보증하지 않고 비 Claude 모델 라우팅도 지원하지 않는다고 명시한다. CLIProxyAPI와 claudex 별칭은 커뮤니티의 비공식 구성으로 봐야 한다.
Q6. 가장 안전한 테스트 방법은 무엇인가요?+
빈 로컬 저장소에서 시작하고 프록시는 127.0.0.1에만 바인딩한다. 실제 토큰을 저장소에 넣지 않고 기본 권한 승인과 샌드박스를 유지한다. 간단한 파일 읽기, 작은 수정, 테스트 실행까지 확인한 뒤에만 중요도가 낮은 실제 프로젝트로 범위를 넓힌다.
출처와 확인 문서
- Theo의 claudex 원문2026년 7월 12일 공개된 구성과 alias
- CLIProxyAPI GitHub프로젝트 개요, Codex OAuth, Claude 호환 API
- CLIProxyAPI 빠른 시작macOS Homebrew 설치와 서비스 설정
- CLIProxyAPI 기본 설정기본 포트, 로컬 바인딩, 설정 파일 위치
- CLIProxyAPI Claude Code 클라이언트Claude Code에서 프록시를 사용하는 환경 변수
- Claude Code 환경 변수base URL, effort, subagent model, tool search 정의
- Claude Code LLM 게이트웨이제3자 게이트웨이의 지원 경계와 운영 주의점
주의: 이 글은 2026년 7월 14일 기준 커뮤니티 설정을 설명합니다. CLIProxyAPI와 claudex는 Anthropic 또는 OpenAI의 공식 통합 제품이 아닙니다. 버전, 모델 제공 여부, 공급자 약관과 인증 정책은 변경될 수 있으므로 실제 적용 전 각 공식 문서를 다시 확인하세요.
'AI > Claude' 카테고리의 다른 글
| Claude Fable 5 정액제, 결국 Pro·Max·Team 플랜에 포함 (0) | 2026.07.18 |
|---|---|
| Claude Code 작동 방식: 에이전트 루프부터 컨텍스트·권한·체크포인트까지 (2) | 2026.07.15 |
| Claude Fable 5 또 연장, 7월 19일까지…OpenAI와의 경쟁 때문일까 (2) | 2026.07.14 |
| Claude Fable 5로 웹 페이지 속도 이슈 원인 파악하기 (1) | 2026.07.07 |
| Claude Fable 5 필드 가이드 후기: AI에게 답보다 미지를 찾게 하라 (4) | 2026.07.04 |
