Claude Code가 /v1/messages 대신 OpenAI 호환 모드를 사용하는 6가지 이유 (NPM 버전 전체 문제 해결 가이드)

작성자 주: NPM으로 설치한 Claude Code는 기본적으로 /v1/messages 인터페이스를 사용해야 하지만, 실제 요청은 /v1/chat/completions로 나가는 경우가 있습니다. 본 글에서는 공식 메커니즘을 바탕으로 6가지 원인을 분석하고, 5단계 빠른 진단 솔루션과 APIYI(apiyi.com) 접속을 위한 올바른 설정 예시를 안내합니다.

공식 문서에 따르면 NPM을 통해 설치된 @anthropic-ai/claude-code는 명령줄 환경에서 항상 /v1/messages 엔드포인트로 요청을 보내야 합니다. 이는 anthropic-version 요청 헤더와 원본 messages 형식을 포함하는 Anthropic의 네이티브 Messages API 프로토콜입니다.

하지만 실제 패킷을 캡처해보면 /v1/chat/completions(OpenAI Chat Completions 형식)로 나가는 경우가 있습니다. 이는 특정 단계에서 프로토콜 변환이나 패키지 이름 혼동이 발생했음을 의미합니다. 이는 Claude Code 자체의 버그가 아니라, 6가지 유형의 흔한 설정/환경 문제입니다.

핵심 가치: 본 글에서는 6가지 원인(서드파티 패키지 오설치, ANTHROPIC_BASE_URL이 호환 게이트웨이를 가리키는 경우, claude-code-router의 가로채기 및 변환 등)을 분석하고, 5단계 빠른 진단 솔루션을 제공하며, APIYI(apiyi.com)를 통해 접속할 때 네이티브 /v1/messages 경로를 확실히 타도록 하는 올바른 설정 예시를 제공합니다.

1. Claude Code는 기본적으로 /v1/messages를 사용해야 합니다: 핵심 메커니즘 해석

문제를 해결하기 전에 공식 Claude Code의 예상 동작을 명확히 파악해야 어디가 잘못되었는지 알 수 있습니다.

1.1 공식 @anthropic-ai/claude-code의 프로토콜 설계

Anthropic이 공식적으로 관리하는 @anthropic-ai/claude-code NPM 패키지는 모든 버전에서 Anthropic 네이티브 Messages API 프로토콜만 사용하며, 구체적인 특징은 다음과 같습니다.

구분	공식 Claude Code 동작
요청 엔드포인트	`POST {ANTHROPIC_BASE_URL}/v1/messages`
요청 헤더	`x-api-key`, `anthropic-version: 2023-06-01`, `anthropic-beta`
요청 본문 형식	`{ "model": "...", "messages": [...], "system": "...", "max_tokens": ... }`
응답 형식	`{ "content": [...], "stop_reason": "...", "usage": {...} }`
스트리밍 응답	SSE 이벤트 스트림 (예: `message_start`, `content_block_delta` 등)

만약 패킷 캡처 결과 /v1/chat/completions, Authorization: Bearer ..., 요청 본문에 choices 배열이 포함되어 있다면, 이는 OpenAI 프로토콜의 특징입니다. 즉, 요청이 공식 Claude Code가 의도한 경로를 따르지 않고 있음을 의미합니다.

1.2 주요 환경 변수의 올바른 의미

공식 Claude Code는 API 동작을 조정하기 위해 다음 환경 변수만을 인식합니다.

# 필수: Anthropic API 키 또는 호환 서비스의 키
ANTHROPIC_AUTH_TOKEN=sk-your-key
# 또는 동일한 의미의 변수:
ANTHROPIC_API_KEY=sk-your-key

# 선택: 사용자 정의 API 게이트웨이 주소 (/v1 접미사 제외)
ANTHROPIC_BASE_URL=https://api.anthropic.com

# 선택: 사용자 정의 모델 ID
ANTHROPIC_MODEL=claude-sonnet-4-5
ANTHROPIC_SMALL_FAST_MODEL=claude-haiku-4-5

주의: 공식 Claude Code에는 OPENAI_BASE_URL, CLAUDE_CODE_USE_OPENAI와 같은 변수가 없습니다. 환경에 이러한 변수명이 있다면 서드파티 래퍼(wrapper)를 사용 중이라는 뜻입니다.

💡 빠른 검증 제안: 터미널에서 which claude를 실행하여 Claude Code 설치 경로를 확인한 후, cat $(which claude) | head -20을 실행해 보세요. @anthropic-ai/claude-code 문구가 보인다면 공식 버전을 설치한 것입니다. 만약 openclaude, claudex, cli-agent-openai-adapter 등의 키워드가 보인다면 그것이 근본 원인입니다.

2. Claude Code가 OpenAI 호환 모드로 작동하는 6가지 주요 원인

발생 확률이 높은 순서대로 정리했으니, 이 순서대로 점검해 보세요.

2.1 원인 1: 서드파티 OpenAI Wrapper 패키지 오설치 (사례의 약 35%)

NPM에는 이름은 비슷하지만 기능이 전혀 다른, OpenAI 호환 변환 전용 "Claude Code" 패키지가 다수 존재합니다. 사용자가 이 중 하나를 잘못 설치했을 가능성이 큽니다.

패키지 이름	실제 기능	기본 프로토콜
`@anthropic-ai/claude-code`	✅ 공식 패키지	`/v1/messages`
`@gitlawb/openclaude`	OpenAI shim	`/v1/chat/completions`
`@aryanjsx/openclaude`	OpenAI shim	`/v1/chat/completions`
`cli-agent-openai-adapter`	프로토콜 변환기	`/v1/chat/completions`
`claude-code-openai-wrapper`	듀얼 프로토콜 wrapper	둘 다 지원
`claudex`	Go 기반 OpenAI 프록시	`/v1/chat/completions`

점검 방법:

# 1. 실제 설치 경로 확인
which claude
# 출력 예시: /usr/local/bin/claude

# 2. 패키지의 package.json 내 name 확인
cat $(npm root -g)/@anthropic-ai/claude-code/package.json 2>/dev/null | grep '"name"'

# 3. 전역에 설치된 모든 claude 관련 패키지 확인
npm list -g --depth=0 | grep -i claude

npm list 결과에 @anthropic-ai/claude-code가 없고 다른 유사 이름의 패키지가 있다면 잘못 설치된 것입니다.

2.2 원인 2: claude-code-router 등 라우팅 도구 설정 (사례의 약 25%)

claude-code-router(CCR)는 커뮤니티에서 인기 있는 오픈소스 도구로, Claude Code 요청을 가로채서 다른 모델(OpenAI, DeepSeek, Zhipu 등)로 전달합니다. 작동 원리는 다음과 같습니다.

로컬 프록시 서버 실행 (기본 http://localhost:3456)
사용자가 ANTHROPIC_BASE_URL을 이 로컬 프록시로 지정
CCR이 /v1/messages 요청을 수신한 후, /v1/chat/completions로 변환하여 대상 모델에 전달
패킷 캡처 시 OpenAI 프로토콜로 보이게 됨

점검 방법:

# 환경 변수 확인
env | grep -i ANTHROPIC

# ANTHROPIC_BASE_URL=http://localhost:3456 또는 http://127.0.0.1:xxx 등이 보인다면
# CCR / claude-code-router와 같은 로컬 프록시일 확률이 높습니다.

2.3 원인 3: ANTHROPIC_BASE_URL이 OpenAI 호환 게이트웨이를 가리킴 (사례의 약 20%)

일부 LLM 게이트웨이(LiteLLM Proxy, OneAPI, Bifrost 등)는 Anthropic 모델 설정을 지원하지만, /v1/chat/completions 인터페이스만 노출하는 경우가 있습니다. 사용자가 ANTHROPIC_BASE_URL을 이런 게이트웨이로 설정하면:

Claude Code는 여전히 /v1/messages로 요청을 보냄
게이트웨이가 404를 반환하거나 자동으로 경로를 재작성(rewrite)함
게이트웨이 내부에서 OpenAI 형식으로 변환하여 상위 모델을 호출함
게이트웨이 이후 지점에서 패킷을 캡처하면 OpenAI 프로토콜로 보임

점검 방법: ANTHROPIC_BASE_URL이 알려진 OpenAI 호환 게이트웨이 주소인지 확인하고, 요청이 실제로 성공(200)하는지 404가 발생하는지 확인하세요.

2.4 원인 4: 서드파티 Wrapper 환경 변수 설정 (사례의 약 10%)

일부 wrapper 패키지는 환경 변수를 통해 프로토콜 모드를 전환합니다. 예를 들어:

# openclaude 전환 변수
CLAUDE_CODE_USE_OPENAI=1
OPENAI_API_KEY=sk-xxx
OPENAI_MODEL=gpt-4o
OPENAI_BASE_URL=https://api.openai.com/v1

NPM으로 공식 패키지를 설치했더라도 PATH에 wrapper 스크립트(예: /usr/local/bin/claude가 실제로는 wrapper인 경우)가 있으면 이 변수들이 적용됩니다.

점검 방법:

# PATH 내 claude라는 이름의 실행 파일 모두 나열
type -a claude

# 관련 환경 변수 확인
env | grep -E 'CLAUDE_CODE|OPENAI_BASE_URL|OPENAI_MODEL'

2.5 원인 5: Shell alias 또는 wrapper 스크립트에 의한 가로채기 (사례의 약 7%)

사용자가 ~/.bashrc 또는 ~/.zshrc에 alias를 설정했을 수 있습니다.

# 이런 alias는 원래 claude 명령어를 대체합니다
alias claude='openclaude'
alias claude='claude-code-router run'

# 또는 같은 이름의 함수 정의
claude() {
  CCR_PROXY=http://localhost:3456 command claude "$@"
}

점검 방법:

# alias 확인
alias | grep claude

# 함수 확인
type claude

# 쉘 시작 파일 확인
grep -nE 'claude' ~/.bashrc ~/.zshrc ~/.profile 2>/dev/null

2.6 원인 6: 패킷 캡처 시점의 오판 (사례의 약 3%)

드물게 패킷 캡처 도구의 배치 위치가 잘못되어, Claude Code가 실제로 보낸 요청이 아닌 다른 요청을 보는 경우가 있습니다.

Claude Code → 로컬 투명 프록시(예: mitmproxy) → 원격 OpenAI 게이트웨이
캡처 도구가 게이트웨이 뒤에 배치되어 게이트웨이가 재작성한 요청을 확인
실제 Claude Code는 /v1/messages를 보냈음

점검 방법: 사용자의 로컬 머신에서 mitmproxy를 사용하여 Claude Code 프로세스를 직접 프록시하고, 첫 번째 요청이 어떤 프로토콜인지 확인하세요.

3. Claude Code 프로토콜 이상 5단계 빠른 진단

아래 순서대로 하나씩 점검해 보세요. 대부분의 프로토콜 이상은 3단계 이내에서 해결됩니다.

3.1 1단계: 공식 NPM 패키지 설치 확인

# 모든 잠재적 wrapper 제거
npm uninstall -g @gitlawb/openclaude @aryanjsx/openclaude cli-agent-openai-adapter claudex claude-code-router 2>/dev/null

# 공식 패키지 제거 후 재설치
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

# 버전 및 출처 검증
claude --version
npm list -g @anthropic-ai/claude-code

통과 조건: npm list -g 출력에 @anthropic-ai/[email protected]가 포함되어야 합니다.

3.2 2단계: PATH 및 쉘 alias 정리

# PATH 내 claude라는 이름의 실행 파일 모두 찾기
type -a claude
which -a claude

# 같은 이름의 alias / function 취소
unalias claude 2>/dev/null
unset -f claude 2>/dev/null

# 쉘 시작 스크립트 내 claude 관련 설정 확인 및 정리
grep -n 'claude' ~/.bashrc ~/.zshrc ~/.profile 2>/dev/null

통과 조건: type -a claude가 npm 전역 디렉토리 내 공식 패키지를 가리키는 경로 하나만 출력해야 합니다.

3.3 3단계: 충돌하는 환경 변수 정리

# 모든 claude / openai 관련 변수 확인
env | grep -iE 'claude|openai|anthropic'

# 충돌 가능성이 있는 변수 정리
unset CLAUDE_CODE_USE_OPENAI
unset OPENAI_BASE_URL
unset OPENAI_MODEL
unset CCR_PROXY

# 공식적으로 필요한 변수만 유지
export ANTHROPIC_BASE_URL="https://vip.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-apiyi-key"

🎯 핵심 주의사항: ANTHROPIC_BASE_URL은 도메인 루트( /v1 접미사 제외)로 입력해야 합니다. Claude Code가 자동으로 /v1/messages를 붙이기 때문입니다. https://vip.apiyi.com/v1으로 입력하면 https://vip.apiyi.com/v1/v1/messages가 되어 404 오류가 발생합니다.

3.4 4단계: base_url이 /v1/messages를 네이티브로 지원하는지 테스트

curl을 사용하여 Claude Code의 요청을 모방하고, 게이트웨이가 Anthropic 네이티브 프로토콜을 실제로 지원하는지 검증합니다.

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

통과 조건: 200 응답과 함께 응답 본문에 "type": "message" 및 "content": [...]가 포함되어야 합니다.

404가 반환되거나 응답 본문이 OpenAI 형식(choices 포함)이라면, 해당 게이트웨이는 Anthropic 네이티브 프로토콜을 지원하지 않는 것입니다. 이 경우 APIYI(apiyi.com)로 전환하면 즉시 해결됩니다. APIYI는 /v1/messages를 네이티브로 지원하며 /v1/chat/completions도 호환되어 두 프로토콜 모두 사용 가능합니다.

3.5 5단계: 로컬 패킷 캡처로 최종 요청 검증

앞의 4단계를 통과했음에도 문제가 있다면 mitmproxy를 사용하여 로컬에서 패킷을 캡처해 보세요.

# mitmproxy 실행 (기본 포트 8080)
mitmproxy --listen-port 8080

# Claude Code가 로컬 프록시를 거치도록 설정
export HTTPS_PROXY=http://localhost:8080
export HTTP_PROXY=http://localhost:8080

# Claude Code 실행
claude

통과 조건: mitmproxy에서 잡힌 첫 번째 요청이 POST /v1/messages이며, 요청 헤더에 anthropic-version이 포함되어 있어야 합니다.

4. APIYI를 통한 Claude Code의 네이티브 `/v1/messages` 연동 설정

APIYI(apiyi.com)는 Anthropic Messages API 프로토콜을 네이티브로 지원하는 몇 안 되는 API 중계 서비스 중 하나입니다. 이를 통해 Claude Code가 /v1/chat/completions가 아닌 /v1/messages 경로를 안정적으로 사용하도록 보장할 수 있습니다.

4.1 환경 변수 설정 (가장 간단한 방법)

# macOS / Linux
export ANTHROPIC_BASE_URL="https://vip.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-apiyi-key"
# 선택 사항: 기본 모델 지정
export ANTHROPIC_MODEL="claude-sonnet-4-5"
export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-4-5"

# Windows PowerShell
$env:ANTHROPIC_BASE_URL = "https://vip.apiyi.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-your-apiyi-key"

# Claude Code 실행
claude

4.2 Shell 시작 파일에 영구 설정 추가

# ~/.zshrc 또는 ~/.bashrc에 추가
cat >> ~/.zshrc <<'EOF'

# Claude Code → APIYI apiyi.com 중계 설정
export ANTHROPIC_BASE_URL="https://vip.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-apiyi-key"
export ANTHROPIC_MODEL="claude-sonnet-4-5"
EOF

# 설정 적용
source ~/.zshrc

4.3 Claude Code 내장 설정 명령 사용 (권장)

Claude Code는 환경 변수 노출을 방지하기 위해 자체 CLI 설정 기능을 제공합니다.

# 방법 1: 대화형 설정
claude /login
# "Custom Endpoint"를 선택하고 https://vip.apiyi.com 및 API 키를 입력하세요.

# 방법 2: 설정 파일 직접 수정
cat > ~/.claude/settings.json <<'EOF'
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://vip.apiyi.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-apiyi-key"
  }
}
EOF

4.4 설정 후 실제 요청 경로 검증

Claude Code 실행 후, 새 터미널에서 다음 명령어로 확인해 보세요.

# 방법 1: mitmproxy로 패킷 캡처 (가장 정확함)
mitmproxy --listen-port 8080
# 다른 터미널에서 Claude Code 실행 시 HTTPS_PROXY=http://localhost:8080 설정

# 방법 2: Claude Code 디버그 로그 활성화
ANTHROPIC_LOG=debug claude
# 로그에서 전체 요청 URL과 메서드를 확인할 수 있습니다.

예상 결과: 모든 요청 URL이 https://vip.apiyi.com/v1/messages여야 하며, 메서드는 POST, 요청 헤더에 anthropic-version: 2023-06-01이 포함되어야 합니다.

4.5 APIYI 연동의 핵심 장점

장점	설명
네이티브 /v1/messages 지원	Claude Code 기본 프로토콜, 변환 손실 없음
동시 지원 /v1/chat/completions	하나의 키로 두 가지 프로토콜 모두 사용 가능
anthropic-beta 헤더 완벽 유지	프롬프트 캐싱, 도구 사용 등 고급 기능 지원
무제한 동시성	Claude Code의 긴 대화 세션에서도 속도 제한 없음
100달러 충전 시 10% 추가	공식 홈페이지 대비 약 15% 저렴한 비용
국내 결제 지원	위챗/알리페이로 간편하게 충전 가능

5. 네이티브 /v1/messages vs OpenAI /v1/chat/completions 프로토콜 비교

두 프로토콜의 핵심 차이를 이해해야 Claude Code가 왜 네이티브 프로토콜을 사용해야만 제 성능을 발휘하는지 알 수 있습니다.

구분	Anthropic /v1/messages	OpenAI /v1/chat/completions
인증 헤더	`x-api-key: sk-...`	`Authorization: Bearer sk-...`
버전 헤더	`anthropic-version: 2023-06-01`	없음 (URL 버전 사용)
특성 헤더	`anthropic-beta: prompt-caching-...`	표준 없음
system 필드	최상위 독립 필드	`messages[0]`의 system 역할로 포함
응답 형식	`{ "content": [...], "stop_reason": "..." }`	`{ "choices": [{ "message": {...} }] }`
스트리밍 이벤트	`message_start`, `content_block_delta` 등 구조화된 이벤트	`data: {...}` 범용 SSE
도구 호출	콘텐츠 블록 내 `tool_use` 임베딩	`choices[0].message.tool_calls`
토큰 카운트	`usage.input_tokens` / `usage.output_tokens`	`usage.prompt_tokens` / `usage.completion_tokens`

핵심 결론: Claude Code는 Anthropic 고유 기능(프롬프트 캐싱, 도구 사용 스트리밍 증분, 추론 콘텐츠 등)을 대량으로 사용합니다. 이를 강제로 OpenAI 프로토콜로 변환하면 이러한 기능이 손실되거나 동작이 일관되지 않게 됩니다. 이것이 바로 Claude Code가 반드시 네이티브 /v1/messages를 사용해야 하는 이유입니다.

6. 각 사용 시나리오별 점검 리스트

6.1 시나리오 1: 개인 개발자 로컬 환경

가장 흔한 원인: Shell alias 또는 PATH에 동일한 이름의 래퍼(wrapper)가 존재함

점검 리스트:

npm list -g 결과에 @anthropic-ai/claude-code가 포함되어 있는지 확인
type -a claude 명령어가 공식 패키지만 가리키고 있는지 확인
~/.zshrc / ~/.bashrc에 alias claude=... 설정이 있는지 확인
env | grep -i claude 결과에 표준적이지 않은 변수가 있는지 확인
ANTHROPIC_BASE_URL에 /v1 접미사가 포함되어 있는지 확인 (포함되지 않아야 함)

6.2 시나리오 2: 팀/회사 환경 배포

가장 흔한 원인: 사내 대규모 언어 모델 게이트웨이가 OpenAI 프로토콜만 지원함

점검 리스트:

사내 게이트웨이가 /v1/messages 엔드포인트를 기본적으로 지원하는지 확인
게이트웨이가 anthropic-version, anthropic-beta 요청 헤더를 전달하는지 확인
게이트웨이가 SSE 이벤트의 원본 형식을 유지하는지 확인
팀 공통 래퍼 스크립트가 적용되어 있는지 확인

만약 사내 게이트웨이가 OpenAI 프로토콜만 지원한다면, 클라이언트의 ANTHROPIC_BASE_URL을 APIYI(apiyi.com)로 변경하여 네이티브 프로토콜을 직접 연결하는 것을 권장합니다. 이를 통해 변환 과정에서 발생하는 손실을 방지할 수 있습니다.

6.3 시나리오 3: CI/CD 환경에서 Claude Code 호출

가장 흔한 원인: CI 스크립트에 서드파티 래퍼가 고정되어 있음

점검 리스트:

CI 설정 파일에서 비공식 패키지를 npm install -g 하고 있는지 확인
CI 환경 변수에 CLAUDE_CODE_USE_OPENAI=1 등이 설정되어 있는지 확인
CI 러너 이미지에 래퍼가 미리 설치되어 있는지 확인

6.4 시나리오 4: Docker 컨테이너 내 실행

가장 흔한 원인: 베이스 이미지에 래퍼가 미리 설치되어 있음

점검 리스트:

Dockerfile 내 RUN npm install -g로 설치하는 패키지명이 공식 패키지인지 확인
컨테이너 내 which claude가 어디를 가리키는지 확인
컨테이너의 ENV에 프로토콜 전환 변수가 설정되어 있는지 확인

7. Claude Code 프로토콜 이상 관련 FAQ

Q1: 공식 @anthropic-ai/claude-code를 설치했는데 왜 OpenAI 프로토콜로 작동하나요?

가장 큰 원인은 ANTHROPIC_BASE_URL이 OpenAI 호환 게이트웨이를 가리키고 있기 때문입니다. 일부 게이트웨이는 /v1/messages 요청을 받으면 내부적으로 /v1/chat/completions로 변환하여 상위 서버로 호출합니다. 패킷 캡처 도구가 게이트웨이 뒤에 배치되어 있다면 변환된 프로토콜을 보게 됩니다.

해결 방법은 ANTHROPIC_BASE_URL을 APIYI(apiyi.com)로 변경하는 것입니다. /v1/messages를 네이티브로 지원하므로 변환 손실 없이 사용할 수 있습니다.

Q2: 모든 Claude 래퍼를 완전히 삭제하려면 어떻게 하나요?

# 모든 claude 관련 전역 패키지 나열
npm list -g --depth=0 | grep -i claude

# 알려진 래퍼 일괄 삭제
npm uninstall -g \
  @gitlawb/openclaude \
  @aryanjsx/openclaude \
  cli-agent-openai-adapter \
  claudex \
  claude-code-router \
  ccr \
  2>/dev/null

# 공식 패키지 재설치
npm install -g @anthropic-ai/claude-code

# 확인
which claude
claude --version

Q3: ANTHROPIC_BASE_URL은 어느 경로까지 입력해야 하나요?

도메인 루트까지만 입력하세요. /v1 접미사는 붙이지 마세요. Claude Code 내부에서 자동으로 /v1/messages를 결합합니다.

# ✅ 올바름
export ANTHROPIC_BASE_URL="https://vip.apiyi.com"

# ❌ 잘못됨 (결과: /v1/v1/messages)
export ANTHROPIC_BASE_URL="https://vip.apiyi.com/v1"

# ❌ 잘못됨 (엔드포인트 경로 포함)
export ANTHROPIC_BASE_URL="https://vip.apiyi.com/v1/messages"

Q4: 왜 일부 튜토리얼에서는 claude-code-router 설치를 권장하나요?

claude-code-router는 커뮤니티 도구로, 주로 Claude Code가 Anthropic 이외의 모델(DeepSeek, Zhipu, 로컬 Ollama 등)을 호출하도록 하기 위해 사용됩니다. 프로토콜 변환을 통해 이를 구현합니다.

만약 Anthropic의 정식 Claude 모델(Claude Sonnet 4.5, Opus 4.7 등)을 사용하고 싶다면 CCR은 전혀 필요 없습니다. APIYI(apiyi.com)를 통해 네이티브 /v1/messages로 접속하면 더 나은 경험과 변환 손실 없는 환경을 누릴 수 있습니다.

Q5: APIYI(apiyi.com)는 /v1/messages와 /v1/chat/completions를 모두 지원하나요?

네, APIYI는 두 프로토콜을 모두 완벽하게 지원합니다.

https://vip.apiyi.com/v1/messages —— Anthropic 네이티브 형식 (Claude Code 기본값)
https://vip.apiyi.com/v1/chat/completions —— OpenAI 호환 형식

하나의 API 키로 두 프로토콜을 모두 사용할 수 있으며, 클라이언트 도구에 따라 자동으로 적응합니다.

Q6: 캡처된 요청 URL이 https://vip.apiyi.com/v1/messages라면 무조건 네이티브 모드인가요?

그렇지 않습니다. 다음 사항을 함께 확인해야 합니다.

요청 헤더에 anthropic-version: 2023-06-01이 포함되어 있는지
요청 본문 상단에 messages 배열과 독립적인 system 필드가 있는지 (messages 내부에 system role이 포함된 형태가 아님)
응답 본문에 "type": "message"와 content: [...]가 포함되어 있는지 ( choices: [...]가 아님)

URL은 /v1/messages이지만 요청 본문이 OpenAI 형식(messages 내부에 system role 포함)이라면, 클라이언트 자체에 변환 계층이 존재한다는 의미입니다.

Q7: Claude Code 디버그 로그를 활성화하는 환경 변수는 무엇인가요?

# 상세한 HTTP 요청/응답 로그 출력
ANTHROPIC_LOG=debug claude

# 또는 verbose 모드 사용
claude --verbose

# Claude Code 자체 진단 정보 확인
claude /doctor

디버그 로그에는 전체 URL, 요청 헤더, 요청 본문(민감 정보는 마스킹됨)이 표시되므로 프로토콜 문제를 파악하는 가장 직접적인 방법입니다.

Q8: 잘 작동하던 Claude Code가 갑자기 OpenAI 프로토콜로 바뀌었습니다. 이유가 무엇일까요?

가장 흔한 원인들:

Claude Code 업데이트 중 npm install -g로 동일한 이름의 서드파티 패키지가 잘못 설치됨
최근 팀에서 LLM 게이트웨이를 배포하고 새로운 ANTHROPIC_BASE_URL을 적용함
macOS 업데이트 후 특정 alias가 다시 활성화됨
회사에서 프로토콜 변환 감사를 위해 투명 프록시를 활성화함

문제 해결 시 최근의 환경 변화(npm 설치 기록, 쉘 설정 변경, 게이트웨이 변경 공지 등)를 우선적으로 확인하세요.

8. Key Takeaways 핵심 요약

✅ 공식 @anthropic-ai/claude-code는 항상 /v1/messages를 사용합니다. 공식적인 OpenAI 호환 모드는 존재하지 않습니다.
✅ 6가지 주요 원인 (확률순): 서드파티 패키지 오설치 / claude-code-router의 가로채기 / base_url이 OpenAI 게이트웨이를 가리킴 / 서드파티 환경 변수 / 쉘 alias 설정 / 패킷 캡처 시 오판.
✅ 5단계 빠른 진단: 패키지 이름 확인 → PATH/alias 정리 → 환경 변수 정리 → curl로 base_url 테스트 → 로컬 패킷 캡처 검증.
✅ ANTHROPIC_BASE_URL에 /v1 접미사를 붙이지 마세요. Claude Code가 자동으로 경로를 결합합니다.
✅ APIYI(apiyi.com)는 /v1/messages를 네이티브로 지원하며, 동시에 /v1/chat/completions도 호환하므로 하나의 키로 두 프로토콜 모두 사용 가능합니다.
✅ 네이티브 프로토콜 사용의 장점: 프롬프트 캐싱(prompt caching), 도구 사용(tool_use), 추론 내용(reasoning content) 등 Anthropic 고유 기능을 완벽하게 지원합니다.
✅ 빠른 검증 방법: ANTHROPIC_LOG=debug claude를 실행하여 실제 요청 URL과 메서드를 확인하세요.

9. 결론

NPM으로 설치한 Claude Code는 명령줄 환경에서 항상 네이티브 /v1/messages 프로토콜을 사용해야 합니다. 이는 공식 @anthropic-ai/claude-code 패키지의 하드코딩된 동작이며, OpenAI 호환 모드로 전환할 수 있는 공식 설정은 없습니다. 만약 패킷 캡처 결과 /v1/chat/completions로 나타난다면, 문제는 반드시 클라이언트 환경의 어딘가에 있습니다. 서드파티 래퍼를 잘못 설치했거나, ANTHROPIC_BASE_URL이 OpenAI 프로토콜만 지원하는 게이트웨이를 가리키고 있거나, 쉘 alias 또는 환경 변수가 요청을 가로채 변환하고 있을 가능성이 큽니다.

본문의 3장에서 제시한 5단계 진단 절차를 따라가면 대부분의 문제는 10분 이내에 해결할 수 있습니다. 가장 흔한 해결책은 비공식 패키지를 모두 삭제하고 → @anthropic-ai/claude-code를 재설치한 뒤 → ANTHROPIC_BASE_URL을 /v1/messages를 네이티브로 지원하는 API 중계 서비스로 설정하는 것입니다.

APIYI(apiyi.com)는 이러한 환경을 위해 설계되었습니다. Anthropic Messages API를 네이티브로 지원( anthropic-version, anthropic-beta 헤더 완벽 전달)함과 동시에 OpenAI Chat Completions도 호환(하나의 키로 이중 프로토콜 지원)하며, 동시 접속 제한이 없어 Claude Code의 긴 세션도 원활하게 처리합니다. 100달러 충전 시 10% 추가 적립(공식 홈페이지 대비 약 15% 할인 효과) 혜택을 제공하며, 위챗/알리페이로 간편하게 결제할 수 있습니다. 설정은 ANTHROPIC_BASE_URL을 https://vip.apiyi.com으로 변경하기만 하면 되며, 별도의 코드 수정은 필요 없습니다.

🎯 다음 단계 제안: 고객에게 본문의 3.1 → 3.2 → 3.3 순서대로 점검하도록 안내하고, ANTHROPIC_BASE_URL을 https://vip.apiyi.com으로 변경한 후 Claude Code를 재시작하세요. 이후 ANTHROPIC_LOG=debug claude를 통해 요청 URL이 /v1/messages로 정상 복구되었는지 확인하시기 바랍니다.

참고 자료

Claude Code 공식 문서: LLM Gateway 설정 안내
- 링크: code.claude.com/docs/en/llm-gateway
- 설명: Claude Code가 Anthropic Messages API 형식을 사용함을 공식 문서에서 명시하고 있습니다.
@anthropic-ai/claude-code NPM 패키지: 공식 NPM 패키지 페이지
- 링크: npmjs.com/package/@anthropic-ai/claude-code
- 설명: 공식 패키지가 올바르게 설치되었는지 확인하세요.
Anthropic Messages API 공식 문서: 네이티브 프로토콜 사양
- 링크: docs.anthropic.com/en/api/messages
- 설명: /v1/messages 엔드포인트의 전체 필드, 요청 헤더, 응답 형식에 대한 상세 정보입니다.
APIYI 공식 홈페이지: 네이티브 Anthropic 프로토콜 API 중계 서비스
- 링크: apiyi.com
- 설명: 네이티브 /v1/messages 및 /v1/chat/completions 호환 지원, 동시성 제한 없음, 100달러 충전 시 10% 추가 증정 혜택을 제공합니다.

작성자: 기술팀
최종 업데이트: 2026-05-02
APIYI 소개: APIYI(apiyi.com)는 전문적인 Claude API 중계 서비스 제공업체입니다. Anthropic Messages API(/v1/messages, anthropic-version, anthropic-beta 포함 전체 패스스루)를 네이티브로 지원하며, OpenAI Chat Completions(/v1/chat/completions)와도 호환됩니다. Claude Sonnet 4.5, Claude Opus 4.7, Claude Haiku 4.5 전 라인업의 안정적인 연결을 제공하며, 100달러 충전 시 10% 추가 증정(공식 홈페이지 대비 약 15% 할인 효과), 동시성 제한 없음, 신속한 기술 지원을 보장합니다.

1. Claude Code는 기본적으로 /v1/messages를 사용해야 합니다: 핵심 메커니즘 해석

1.1 공식 @anthropic-ai/claude-code의 프로토콜 설계

1.2 주요 환경 변수의 올바른 의미

2. Claude Code가 OpenAI 호환 모드로 작동하는 6가지 주요 원인

2.1 원인 1: 서드파티 OpenAI Wrapper 패키지 오설치 (사례의 약 35%)

2.2 원인 2: claude-code-router 등 라우팅 도구 설정 (사례의 약 25%)

2.3 원인 3: ANTHROPIC_BASE_URL이 OpenAI 호환 게이트웨이를 가리킴 (사례의 약 20%)

2.4 원인 4: 서드파티 Wrapper 환경 변수 설정 (사례의 약 10%)

2.5 원인 5: Shell alias 또는 wrapper 스크립트에 의한 가로채기 (사례의 약 7%)

2.6 원인 6: 패킷 캡처 시점의 오판 (사례의 약 3%)

3. Claude Code 프로토콜 이상 5단계 빠른 진단

3.1 1단계: 공식 NPM 패키지 설치 확인

3.2 2단계: PATH 및 쉘 alias 정리

3.3 3단계: 충돌하는 환경 변수 정리

3.4 4단계: base_url이 /v1/messages를 네이티브로 지원하는지 테스트

3.5 5단계: 로컬 패킷 캡처로 최종 요청 검증

4. APIYI를 통한 Claude Code의 네이티브 /v1/messages 연동 설정

4.1 환경 변수 설정 (가장 간단한 방법)

4.2 Shell 시작 파일에 영구 설정 추가

4.3 Claude Code 내장 설정 명령 사용 (권장)

4.4 설정 후 실제 요청 경로 검증

4.5 APIYI 연동의 핵심 장점

5. 네이티브 /v1/messages vs OpenAI /v1/chat/completions 프로토콜 비교

6. 각 사용 시나리오별 점검 리스트

6.1 시나리오 1: 개인 개발자 로컬 환경

6.2 시나리오 2: 팀/회사 환경 배포

6.3 시나리오 3: CI/CD 환경에서 Claude Code 호출

6.4 시나리오 4: Docker 컨테이너 내 실행

7. Claude Code 프로토콜 이상 관련 FAQ

Q1: 공식 @anthropic-ai/claude-code를 설치했는데 왜 OpenAI 프로토콜로 작동하나요?

Q2: 모든 Claude 래퍼를 완전히 삭제하려면 어떻게 하나요?

Q3: ANTHROPIC_BASE_URL은 어느 경로까지 입력해야 하나요?

Q4: 왜 일부 튜토리얼에서는 claude-code-router 설치를 권장하나요?

Q5: APIYI(apiyi.com)는 /v1/messages와 /v1/chat/completions를 모두 지원하나요?

Q6: 캡처된 요청 URL이 https://vip.apiyi.com/v1/messages라면 무조건 네이티브 모드인가요?

Q7: Claude Code 디버그 로그를 활성화하는 환경 변수는 무엇인가요?

Q8: 잘 작동하던 Claude Code가 갑자기 OpenAI 프로토콜로 바뀌었습니다. 이유가 무엇일까요?

8. Key Takeaways 핵심 요약

9. 결론

참고 자료

Similar Posts

4. APIYI를 통한 Claude Code의 네이티브 `/v1/messages` 연동 설정