Claudex 게이트웨이

Claudex 게이트웨이은(는) 무엇을 하나요?

개요

이 스킬을 사용하여 사용자의 로컬 Claude Code -> Codex OAuth 게이트웨이를 안전하고 일관되게 운영하세요. 사용자가 명시적으로 재설계를 요청하지 않는 한, CLAUDEX_GATEWAY_HOME 아래에 배포된 스택을 진실 공급원(source of truth)으로 취급하세요. 이 스킬에서는 다음 규칙을 사용합니다:

• SKILL_ROOT: 이 claudex-gateway 스킬 디렉토리의 설치 경로
• CLAUDEX_GATEWAY_HOME: 로컬 프록시 스택의 런타임 디렉토리. 설정되지 않은 경우, 헬퍼 스크립트는 먼저 ${XDG_DATA_HOME:-$HOME/.local/share}/claudex-gateway를 찾고, 그 다음 레거시 경로인 ${XDG_DATA_HOME:-$HOME/.local/share}/cliproxyapi-codex-test를 찾습니다.
• CLAUDEX_WRAPPER: claudex 래퍼 경로. 설정되지 않은 경우, 기본값은 ${HOME}/.local/bin/claudex입니다.

빠른 시작

• 새 머신 부트스트랩: python3 "$SKILL_ROOT/scripts/bootstrap_stack.py"
• ~/.codex/auth.json에서 로컬 인증 파일 새로고침: python3 "$SKILL_ROOT/scripts/sync_codex_auth.py"
• 현재 게이트웨이 상태 확인: claudex status
• 로컬 프록시 재시작: claudex restart
• 스택 스모크 테스트: python3 "$SKILL_ROOT/scripts/probe_stack.py"
• 래퍼를 통해 Claude Code 실행: claudex --resume

워크플로우

0. 게이트웨이 스택이 아직 없으면 먼저 부트스트랩

• CLAUDEX_GATEWAY_HOME이 없으면, 파일을 하나하나 수동으로 만들지 마세요.
• python3 "$SKILL_ROOT/scripts/bootstrap_stack.py"를 실행하여 런타임 디렉토리, 설정, 실행기, 환경 파일, status/start/stop/restart를 포함한 claudex 래퍼, 그리고 빌드된 cli-proxy-api 바이너리를 생성하세요.
• 부트스트랩 스크립트는 다음이 이미 설치되었다고 가정합니다: codex와 claude git과 go (CLIProxyAPI 클론 및 빌드용)
• 부트스트랩 후, 다른 문제를 디버깅하기 전에 인증을 동기화하고 프록시를 시작하세요.

1. 어떤 경로가 사용 중인지 확인

• 작업 경로가 다음과 같다고 가정합니다: Claude Code -> claudex 래퍼 -> CLIProxyAPI -> chatgpt.com/backend-api/codex
• 사용자가 현재 claudex 설정에 대해 질문할 때는 LiteLLM부터 시작하지 마세요.
• 아키텍처를 변경하거나 트레이드오프를 설명하기 전에 current-stack.md를 읽으세요.

2. 동작이 오래된 것처럼 보이면 먼저 자격 증명 새로고침

• python3 "$SKILL_ROOT/scripts/sync_codex_auth.py" 실행
• 이 명령은 현재 Codex OAuth 토큰을 ~/.codex/auth.json에서 프록시 인증 파일로 복사합니다: "$CLAUDEX_GATEWAY_HOME/auth/codex-current.json"
• 사용자가 Codex에서 로그아웃된 경우, 중단하고 먼저 다시 인증하세요.

3. Claude Code를 건드리기 전에 로컬 프록시 확인

• 원시 러너 호출보다 래퍼 명령어를 선호하세요: claudex status claudex start claudex restart
• 상태, /v1/messages, 도구 사용, 토큰 카운팅 확인: python3 "$SKILL_ROOT/scripts/probe_stack.py"
• 래퍼 생성 자체를 디버깅할 때만 원시 run.sh를 사용하세요.

4. 사용자가 더 깊은 변경을 요청하지 않는 한, 환경 파일에서만 모델 라우팅 변경

• 래퍼 claudex는 다음을 소싱합니다: "$CLAUDEX_GATEWAY_HOME/claude-code-gpt54.env"
• 현재 매핑은 거기에 유지됩니다.
• CLAUDEX_WRAPPER의 래퍼 계약을 유지하세요: 서브커맨드를 먼저 서비스 그렇지 않으면 env를 소싱하고 exec "$CLAUDE_BIN" "$@" 실행
• 항상 원시 인자 전달을 유지하세요. claudex --resume은 env를 주입한 상태에서 claude --resume과 동일하게 동작해야 합니다.

5. 배포된 바이너리가 없거나 손상된 경우에만 재빌드

• 배포된 바이너리: "$CLAUDEX_GATEWAY_HOME/cli-proxy-api"
• 재빌드가 필요한 경우, 업스트림 저장소 사용: git clone --depth=1 https://github.com/router-for-me/CLIProxyAPI.git /tmp/CLIProxyAPI cd /tmp/CLIProxyAPI && go build -o "$CLAUDEX_GATEWAY_HOME/cli-proxy-api" ./cmd/server
• 사용자가 요청하지 않는 한, 런타임 설정과 인증 디렉토리는 그대로 두세요.

중요 규칙

• 사용자가 명시적으로 재설계를 요청하지 않는 한, CLIProxyAPI를 LiteLLM으로 교체하여 스택을 "수정"하지 마세요.
• 포트, 인증 파일 위치, 또는 래퍼 의미를 조용히 변경하지 마세요.
• claudex 인자 전달을 깨뜨리지 마세요.
• 병렬 변형을 만드는 대신 현재 배포된 파일을 편집하는 것을 선호하세요.
• 스택을 설명할 때, 작업 경로가 chatgpt.com/backend-api/codex를 사용하며, api.openai.com에 직접 Responses 호출을 사용하지 않는다는 점을 명시적으로 밝히세요.

리소스

scripts/

• bootstrap_stack.py: 새 머신에 로컬 게이트웨이 런타임 생성
• sync_codex_auth.py: ~/.codex/auth.json에서 프록시 인증 파일 새로고침
• probe_stack.py: 상태, Claude 메시지, 도구 사용, 토큰 카운팅 확인
• show_status.sh: 현재 파일 레이아웃, env 매핑, 포트 상태 출력

references/

• current-stack.md: 배경, 파일 레이아웃, 명령어, 문제 해결 참고 사항