Claude Code OpenAI API Wrapper

OpenAI API와 호환되는 Claude Code 래퍼로, 모든 OpenAI 클라이언트 라이브러리를 사용하여 Claude Code를 사용할 수 있게 합니다. 이제 향상된 인증 및 기능과 함께 공식 Claude Code Python SDK가 구동합니다.

상태 (Status)

🎉 운영 환경 준비 완료 (Production Ready) - 모든 핵심 기능이 작동하고 테스트되었습니다:

• ✅ 공식 Claude Code Python SDK를 사용한 채팅 완성(Chat completions) 엔드포인트
• ✅ 스트리밍 및 비스트리밍 응답
• ✅ 전체 OpenAI SDK 호환성
• ✅ 다중 공급자 인증 (Multi-provider authentication) (API 키, Bedrock, Vertex AI, CLI 인증)
• ✅ SDK 옵션을 통한 시스템 프롬프트 지원
• ✅ 유효성 검사를 포함한 모델 선택 지원
• ✅ 기본적으로 빠름 (Fast by default) - OpenAI 호환성을 위해 도구 사용이 비활성화되어 있습니다 (5~10배 더 빠름)
• ✅ 명시적으로 활성화된 경우의 선택적 도구 사용 (Read, Write, Bash 등)
• ✅ SDK를 통한 실시간 비용 및 토큰 추적
• ✅ 요청 간 대화 기록을 통한 세션 연속성 (Session continuity) 🆕
• ✅ 전체 세션 제어를 위한 세션 관리 엔드포인트 🆕
• ✅ 상태, 인증, 모델 엔드포인트
• ✅ 자동 리로드 기능이 있는 개발 모드 (Development mode)

기능 (Features)

🔥 핵심 API 호환성 (Core API Compatibility)

• OpenAI와 호환되는 /v1/chat/completions 엔드포인트
• 스트리밍 및 비스트리밍 응답 모두 지원
• OpenAI Python SDK 및 모든 OpenAI 클라이언트 라이브러리와 호환
• 자동 모델 유효성 검사 및 선택 기능

🛠 Claude Code SDK 통합 (Claude Code SDK Integration)

• 공식 Claude Code Python SDK 통합 (v0.0.14)
• 실시간 비용 추적 - SDK 메타데이터를 통한 실제 비용 계산
• 정확한 토큰 카운팅 - SDK를 통한 입력/출력 토큰 수 측정
• 세션 관리 - 적절한 세션 ID 및 연속성 유지
• 상세한 인증 진단이 포함된 향상된 오류 처리 기능

🔐 다중 공급자 인증 (Multi-Provider Authentication)

• 자동 감지된 인증 방식
• Claude CLI 인증: 기존 claude auth 설정과 연동
• 직접 API 키: ANTHROPIC_API_KEY 환경 변수 사용
• AWS Bedrock: AWS 자격 증명을 이용한 엔터프라이즈급 인증
• Google Vertex AI: GCP 인증 지원

⚡ 고급 기능 (Advanced Features)

• SDK 옵션을 통한 시스템 프롬프트 지원
• 필요에 따른 선택적 도구 사용 (Optional tool usage): Claude Code 도구(읽기, 쓰기, Bash 등) 활성화
• 빠른 기본 모드 (Fast default mode): OpenAI API 호환성을 위해 도구 비활성화가 기본값임
• 자동 리로드 기능이 있는 개발 모드: (uvicorn --reload)
• 대화형 API 키 보호: 자동으로 생성된 토큰을 이용한 선택적 보안 강화
• 포괄적인 로깅 및 디버깅 기능

빠른 시작 (Quick Start)

2분 안에 시작하세요:

# 1. Claude Code CLI 설치 (아직 설치되지 않은 경우)
npm install -g @anthropic-ai/claude-code

...

🎉 끝! OpenAI와 호환되는 Claude Code API가 http://localhost:8000에서 실행됩니다.

사전 요구 사항 (Prerequisites)

1. Claude Code CLI: Claude Code CLI 설치

   복사

   # Claude Code 설치 (Anthropic 공식 가이드 따름)
   npm install -g @anthropic-ai/claude-code
   

   1

   2

   3

2. 인증 (Authentication): 다음 방법 중 하나를 선택하세요:

   • 옵션 A: CLI를 통한 인증 (개발에 권장)
     복사

     claude auth login
     

     1

     2
   • 옵션 B: 환경 변수 설정
     복사

     export ANTHROPIC_API_KEY=your-api-key
     

     1

     2
   • 옵션 C: AWS Bedrock 또는 Google Vertex AI 사용 (설정 섹션 참조)

3. Python 3.10+: 서버 실행에 필수적입니다.

4. Poetry: 의존성 관리를 위해 필요합니다.

   복사

   # Poetry 설치 (아직 설치되지 않은 경우)
   curl -sSL https://install.python-poetry.org | python3 -
   

   1

   2

   3

설치 (Installation)

1. 리포지토리 클론:

   복사

   git clone https://github.com/RichardAtCT/claude-code-openai-wrapper
   cd claude-code-openai-wrapper
   

   1

   2

   3

2. Poetry를 사용하여 종속성(dependencies) 설치:

   복사

   poetry install
   

   1

   2

   이 명령어는 가상 환경을 생성하고 모든 종속성을 설치합니다.

3. 환경 설정 구성:

   복사

   cp .env.example .env
   # 선호하는 대로 .env 파일을 수정하세요
   

   1

   2

   3

설정 구성 (Configuration)

.env 파일 수정하기:

# Claude CLI 경로 (일반적으로 "claude"입니다)
CLAUDE_CLI_PATH=claude

...

🔐 API 보안 구성

서버는 안전한 원격 액세스를 위해 대화형 API 키 보호(interactive API key protection) 기능을 지원합니다:

1. API 키가 설정되지 않은 경우: 서버는 시작 시 "API 키 보호를 활성화하시겠습니까? (y/N)"라는 메시지를 표시합니다.

   • 아니요(No) 선택 (기본값): 인증 없이 서버가 실행됩니다.
   • 예(Yes) 선택: 서버가 안전한 API 키를 생성하고 표시합니다.

2. 환경에 API 키가 설정된 경우: 프롬프트 요청 없이 구성된 API_KEY를 사용합니다.

# 예시: 대화형 보호 활성화
poetry run python main.py

...

다음과 같은 상황에 완벽합니다:

• 🏠 로컬 개발(Local development) - 인증이 필요하지 않습니다.
• 🌐 원격 액세스(Remote access) - 생성된 토큰으로 안전하게 보호됩니다.
• 🔒 VPN/Tailscale - 원격 엔드포인트에 보안 계층을 추가합니다.

서버 실행하기 (Running the Server)

1. Claude Code가 설치되어 작동하는지 확인합니다:

   복사

   claude --version
   claude --print --model claude-3-5-haiku-20241022 "Hello"  # 가장 빠른 모델로 테스트
   

   1

   2

   3

2. 서버를 시작합니다:

   개발 모드 (권장 - 변경 사항에 따라 자동 재로드):

   복사

   poetry run uvicorn main:app --reload --port 8000
   

   1

   2

   운영(Production) 모드:

   복사

   poetry run python main.py
   

   1

   2

   운영 모드의 포트 옵션:

   • 기본값: 포트 8000을 사용합니다 (또는 .env 파일의 PORT 변수).
   • 포트가 이미 사용 중인 경우, 자동으로 다음 사용 가능한 포트를 찾습니다.
   • 사용자 지정 포트 지정: poetry run python main.py 9000
   • 환경 변수로 설정: PORT=9000 poetry run python main.py

사용 예시 (Usage Examples)

curl 사용하기

# 기본 채팅 완료(chat completion) 요청 (인증 없음)
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
...

OpenAI Python SDK 사용하기

from openai import OpenAI

# 클라이언트 설정 (인증 요구 사항을 자동으로 감지합니다)
...

지원 모델(Supported Models)

• claude-sonnet-4-20250514 (권장)
• claude-opus-4-20250514
• claude-3-7-sonnet-20250219
• claude-3-5-sonnet-20241022
• claude-3-5-haiku-20241022

모델 매개변수는 --model 플래그를 통해 Claude Code에 전달됩니다.

세션 연속성(Session Continuity) 🆕

이 Wrapper는 이제 세션 연속성을 지원하여 여러 요청에 걸쳐 대화 컨텍스트를 유지할 수 있습니다. 이는 표준 OpenAI API를 넘어선 강력한 기능입니다.

작동 방식(How It Works)

• Stateless 모드 (기본값): 각 요청은 독립적이며, 일반적인 OpenAI API와 같습니다.
• Session 모드: session_id를 포함하여 요청 간에 대화 기록을 유지합니다.

OpenAI SDK를 사용한 세션 활용(Using Sessions with OpenAI SDK)

import openai

client = openai.OpenAI(
...

curl을 사용한 세션 활용(Using Sessions with curl)

# 첫 번째 메시지 (인증이 활성화된 경우 -H "Authorization: Bearer your-key" 추가)
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
...

세션 관리(Session Management)

이 Wrapper는 활성 세션을 관리하기 위한 엔드포인트를 제공합니다:

• GET /v1/sessions - 모든 활성 세션 목록 가져오기
• GET /v1/sessions/{session_id} - 세부 정보 가져오기
• DELETE /v1/sessions/{session_id} - 세션 삭제하기
• GET /v1/sessions/stats - 세션 통계 가져오기

# 활성 세션 목록 보기
curl http://localhost:8000/v1/sessions

...

세션 기능(Session Features)

• 자동 만료: 비활성화 후 1시간이 지나면 세션이 만료됩니다.
• 스트리밍 지원: 세션 연속성은 스트리밍 및 비스트리밍 요청 모두에서 작동합니다.
• 메모리 영속성: 전체 대화 기록은 세션 내에 유지됩니다.
• 효율적인 저장소: 활성 세션만 메모리에 보관됩니다.

예시(Examples)

종합적인 Python 예시는 examples/session_continuity.py를, curl 예시는 examples/session_curl_example.sh를 참조하십시오.

API 엔드포인트(API Endpoints)

핵심 엔드포인트

• POST /v1/chat/completions - OpenAI와 호환되는 채팅 완료 (세션 ID 지원)
• GET /v1/models - 사용 가능한 모델 목록 조회
• GET /v1/auth/status - 인증 상태 및 설정 확인
• GET /health - 헬스 체크 엔드포인트

세션 관리 엔드포인트 🆕

• GET /v1/sessions - 모든 활성 세션 목록 조회
• GET /v1/sessions/{session_id} - 상세 세션 정보 가져오기
• DELETE /v1/sessions/{session_id} - 특정 세션 삭제
• GET /v1/sessions/stats - 세션 관리자 통계 조회

제한 사항 및 로드맵

🚫 현재 제한 사항

• 메시지 내 이미지: 텍스트 플레이스홀더로 변환됨
• 함수 호출 (Function calling): 지원되지 않음 (도구는 프롬프트를 기반으로 자동으로 작동)
• OpenAI 매개변수 미매핑: temperature, top_p, max_tokens, logit_bias, presence_penalty, frequency_penalty
• 다중 응답 (n > 1): 지원되지 않음

🛣 계획된 개선 사항

• 도구 설정 (Tool configuration) - 허용/금지 도구 엔드포인트
• OpenAI 매개변수 매핑 - temperature, top_p, max_tokens 지원
• 향상된 스트리밍 (Enhanced streaming) - 더 나은 청크 처리
• MCP 통합 (Model Context Protocol) - Model Context Protocol 서버 지원

✅ 최근 개선 사항

• ✅ SDK 통합: 공식 Python SDK가 subprocess 호출을 대체함
• ✅ 실제 메타데이터: SDK를 통해 정확한 비용 및 토큰 수량 제공
• ✅ 다중 인증 (Multi-auth): CLI, API 키, Bedrock, Vertex AI 인증 지원
• ✅ 세션 ID: 적절한 세션 추적 및 관리 기능
• ✅ 시스템 프롬프트 (System Prompts): SDK 옵션을 통한 전체 지원
• ✅ 세션 연속성 (Session Continuity): 세션 관리를 통해 요청 간 대화 기록 유지

문제 해결

1. Claude CLI를 찾을 수 없음:

   복사

   # Claude가 PATH에 있는지 확인
   which claude
   # 필요한 경우 .env 파일에서 CLAUDE_CLI_PATH 업데이트
   

   1

   2

   3

   4

2. 인증 오류 (Authentication errors):

   복사

   # 가장 빠른 모델로 인증 테스트 실행
   claude --print --model claude-3-5-haiku-20241022 "Hello"
   # 실패 시, 필요에 따라 재인증합니다
   

   1

   2

   3

   4

3. 시간 초과 오류 (Timeout errors):

   • .env 파일에서 MAX_TIMEOUT 값을 늘리세요.
   • 참고: Claude Code는 복잡한 요청의 경우 시간이 걸릴 수 있습니다.

테스트 (Testing)

🧪 간편 테스트 스위트 (Quick Test Suite)

모든 엔드포인트를 간단한 스크립트로 테스트합니다:

# 서버가 먼저 실행되었는지 확인하세요
poetry run python test_endpoints.py

📝 기본 테스트 스위트 (Basic Test Suite)

종합적인 테스트 스위트를 실행합니다:

# 서버가 먼저 실행되었는지 확인하세요  
poetry run python test_basic.py

...

테스트 스위트는 API 키 보호 기능이 활성화되어 있는지 자동으로 감지하고, 필요한 인증 정보를 제공하는 데 도움이 되는 안내를 제공합니다.

🔍 인증 테스트 (Authentication Test)

인증 상태를 확인하세요:

curl http://localhost:8000/v1/auth/status | python -m json.tool

⚙️ 개발 도구 (Development Tools)

# 개발 종속성 설치
poetry install --with dev

...

✅ 예상 결과 (Expected Results)

모든 테스트는 다음을 보여야 합니다:

• 4/4 엔드포인트 테스트 통과
• 4/4 기본 테스트 통과
• 감지된 인증 방식 (claude_cli, anthropic, bedrock, 또는 vertex)
• 실제 비용 추적 (예: 테스트 호출당 $0.001-$0.005)
• SDK 메타데이터에서 가져온 정확한 토큰 수

라이선스 (License)

MIT License

기여 (Contributing)

기여를 환영합니다! 이슈를 열거나 풀 리퀘스트(pull request)를 제출해 주세요.