Claude Code를 DeepSeek V4, OpenRouter 또는 다른 타사 모델 공급자에 연결할 때 Invalid custom3p enterprise config 오류가 발생했다면, 대부분은 URL, 인증 헤더, settings.json, 온보딩 상태 중 하나가 잘못된 경우입니다. 이 글에서는 Claude Code의 custom3p 구성이 무엇인지, 어떤 순서로 확인해야 하는지, OpenRouter·LiteLLM·vLLM에서 바로 적용할 수 있는 설정 예시를 정리합니다.
빠른 체크리스트
Invalid custom3p enterprise config는 Claude Code가 타사 공급자 구성을 검증하지 못했다는 뜻입니다.
먼저 아래 순서대로 확인하세요.
-
ANTHROPIC_BASE_URL끝에/v1이 붙어 있지 않은지 확인 - 공급자가 요구하는 인증 방식에 맞게
ANTHROPIC_AUTH_TOKEN또는ANTHROPIC_API_KEY사용 -
~/.claude/settings.json이 유효한 JSON인지 검증 - 새 설치라면
~/.claude.json에 온보딩 완료 플래그가 있는지 확인 - 프록시·게이트웨이가
anthropic-beta,anthropic-version등 필수 헤더를 전달하는지 확인 - 팀/엔터프라이즈 관리 정책이 로컬 설정을 덮어쓰고 있지 않은지 확인
가장 흔한 원인은 ANTHROPIC_BASE_URL 끝의 /v1입니다. 이 항목부터 확인하면 상당수의 문제를 바로 해결할 수 있습니다.
custom3p가 의미하는 것
Claude Code는 요청을 다음 모드 중 하나로 라우팅합니다.
| 모드 | 트리거 방식 |
|---|---|
| Anthropic API 기본값 | 오버라이드 설정 없음 |
| Amazon Bedrock | CLAUDE_CODE_USE_BEDROCK=1 |
| Google Vertex AI | CLAUDE_CODE_USE_VERTEX=1 |
| Microsoft Foundry | CLAUDE_CODE_USE_FOUNDRY=1 |
| 커스텀 타사 공급자 |
ANTHROPIC_BASE_URL이 Anthropic이 아닌 엔드포인트를 가리킴 |
여기서 마지막 항목이 Claude Code 내부에서 말하는 custom3p입니다.
예를 들어 ANTHROPIC_BASE_URL을 LiteLLM, OpenRouter, 로컬 vLLM 서버, 사내 LLM 게이트웨이로 설정하면 Claude Code는 해당 경로를 custom3p로 취급하고 첫 API 호출 전에 엔터프라이즈 구성 검사를 수행합니다.
이 검사가 실패하면 다음 오류가 발생합니다.
Invalid custom3p enterprise config
이 오류는 정책 차단이 아니라 구성 검증 오류입니다. 따라서 설정을 수정하면 해결할 수 있습니다.
왜 이 오류가 자주 발생하는가
2026년 4월 Anthropic은 Claude Code 클라이언트 ID를 위장해 Claude Pro 및 Max 구독에 접근하던 일부 타사 에이전트 도구를 차단했습니다. OpenClaw처럼 Claude Code 세션을 자체 백엔드로 라우팅하던 도구는 이 변경 이후 작동하지 않게 되었습니다.
하지만 이 글에서 다루는 문제는 그 차단과 별개입니다.
많은 개발자가 이후 Claude Code의 공식 타사 공급자 지원을 사용해 더 저렴한 모델 백엔드로 라우팅하기 시작했습니다. 예를 들어 한 Reddit 스레드는 Claude Code 에이전트 루프를 OpenRouter를 통한 DeepSeek V4 Pro로 전환하면 Anthropic의 백만 출력 토큰당 $15 대비 $0.87 수준으로 사용할 수 있다고 설명했습니다. DeepClaude 같은 프로젝트는 이를 단일 명령 설정으로 패키징했습니다.
문제는 Claude Code의 타사 공급자 지원이 정확한 엔터프라이즈 구성을 요구한다는 점입니다. URL, 인증 변수, JSON 형식, 헤더 중 하나라도 잘못되면 Invalid custom3p enterprise config가 발생합니다.
원인 1: ANTHROPIC_BASE_URL 끝에 /v1을 붙임
Claude Code는 설정된 기본 URL 뒤에 자동으로 /v1/messages를 추가합니다.
따라서 기본 URL에 이미 /v1이 포함되어 있으면 실제 요청 경로가 다음처럼 중복됩니다.
/v1/v1/messages
이 경우 게이트웨이는 보통 404를 반환합니다.
잘못된 설정
export ANTHROPIC_BASE_URL="https://api.openrouter.ai/api/v1"
export ANTHROPIC_BASE_URL="https://litellm.yourcompany.com/v1"
올바른 설정
export ANTHROPIC_BASE_URL="https://api.openrouter.ai/api"
export ANTHROPIC_BASE_URL="https://litellm.yourcompany.com"
URL 확인 방법
Claude Code가 실제로 호출할 엔드포인트를 curl로 확인합니다.
curl -s -o /dev/null -w "%{http_code}" \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
"${ANTHROPIC_BASE_URL}/v1/messages" \
-d '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"hi"}]}'
판단 기준은 다음과 같습니다.
| 응답 코드 | 의미 |
|---|---|
200 |
엔드포인트와 인증이 정상일 가능성이 높음 |
400 |
요청 본문은 잘못됐지만 엔드포인트는 존재함 |
404 |
기본 URL에 /v1 중복 가능성 높음 |
401 / 403
|
인증 변수 또는 키 문제 |
원인 2: 인증 변수를 잘못 사용함
Claude Code는 인증 방식에 따라 서로 다른 환경 변수를 사용합니다.
| 변수 | 전송 헤더 | 사용 대상 |
|---|---|---|
ANTHROPIC_API_KEY |
x-api-key |
Anthropic 형식 API 키 인증 게이트웨이 |
ANTHROPIC_AUTH_TOKEN |
Authorization: Bearer |
OAuth 스타일 게이트웨이, LiteLLM, 대부분의 OpenRouter 설정 |
OpenRouter 예시
OpenRouter는 Bearer 토큰을 기대합니다.
export ANTHROPIC_AUTH_TOKEN="sk-or-your-openrouter-key"
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
OpenRouter에서 ANTHROPIC_API_KEY를 사용하면 Claude Code는 x-api-key 헤더를 보냅니다. OpenRouter가 이 헤더를 사용하지 않으면 인증이 실패하고 Claude Code는 이를 엔터프라이즈 구성 오류로 표시할 수 있습니다.
LiteLLM 예시
export ANTHROPIC_AUTH_TOKEN="sk-litellm-your-virtual-key"
export ANTHROPIC_BASE_URL="https://your-litellm-server:4000"
API 키 기반 vLLM 또는 DeepSeek 게이트웨이 예시
export ANTHROPIC_API_KEY="your-key-here"
export ANTHROPIC_BASE_URL="https://your-vllm-server"
게이트웨이 문서에서 어떤 헤더를 요구하는지 먼저 확인하세요.
원인 3: settings.json 형식 오류
환경 변수 대신 ~/.claude/settings.json에 설정을 저장할 수 있습니다. 이 파일이 잘못된 JSON이면 Claude Code는 요청을 보내기 전에 구성 검증에서 실패합니다.
잘못된 예: 끝 쉼표
{
"env": {
"ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
"ANTHROPIC_AUTH_TOKEN": "sk-or-your-key",
}
}
JSON에서는 마지막 속성 뒤에 쉼표를 붙일 수 없습니다.
잘못된 예: 스마트 따옴표
문서나 워드프로세서에서 복사하면 " " 대신 “ ”가 들어갈 수 있습니다.
{
"env": {
“ANTHROPIC_BASE_URL”: “https://openrouter.ai/api”
}
}
올바른 예
{
"env": {
"ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
"ANTHROPIC_AUTH_TOKEN": "sk-or-your-openrouter-key"
}
}
JSON 검증
python3 -c "import json, os; json.load(open(os.path.expanduser('~/.claude/settings.json')))" && echo "Valid JSON"
또는 jq를 사용할 수 있습니다.
jq . ~/.claude/settings.json
여기서 파싱 오류가 발생하면 Claude Code도 설정을 읽지 못합니다.
원인 4: 새 설치 후 온보딩이 완료되지 않음
Claude Code는 ~/.claude/settings.json의 엔터프라이즈 구성을 읽기 전에 ~/.claude.json에서 다음 플래그를 확인합니다.
"hasCompletedOnboarding": true
새로 설치한 환경에서는 이 값이 없거나 false일 수 있습니다. 이 경우 Claude Code는 사용자 지정 타사 구성을 건너뛰고 기본 인증 흐름을 시도할 수 있습니다.
현재 상태 확인
cat ~/.claude.json | python3 -m json.tool 2>/dev/null | grep hasCompletedOnboarding
값이 없거나 false라면 온보딩 플래그를 추가합니다.
{
"hasCompletedOnboarding": true,
"primaryApiKey": "sk-placeholder"
}
primaryApiKey는 플레이스홀더입니다. 엔터프라이즈 구성에 의해 재정의됩니다. 형식 검사를 통과하려면 sk-로 시작하는 값을 넣고 Claude Code를 다시 시작하세요.
원인 5: 게이트웨이가 필수 헤더를 전달하지 않음
Claude Code의 엔터프라이즈 구성 검증에는 기능 핸드셰이크가 포함됩니다. 이 과정에서 게이트웨이에 여러 헤더를 전달합니다.
게이트웨이가 다음 헤더를 제거하면 Claude Code는 예상과 다른 응답을 받고 Invalid custom3p enterprise config를 표시할 수 있습니다.
anthropic-beta
anthropic-version
X-Claude-Code-Session-Id
LiteLLM은 v1.82.9 이상에서 기본적으로 이 흐름을 처리합니다. 직접 Nginx나 사내 프록시를 구성한다면 헤더 전달을 명시해야 합니다.
location /v1/ {
proxy_pass http://backend;
proxy_set_header anthropic-beta $http_anthropic_beta;
proxy_set_header anthropic-version $http_anthropic_version;
proxy_set_header X-Claude-Code-Session-Id $http_x_claude_code_session_id;
}
게이트웨이를 수정할 수 없다면 베타 기능 핸드셰이크를 비활성화할 수 있습니다.
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
이 설정은 일부 실험 기능 접근을 제한할 수 있지만, 핵심 에이전트 루프는 계속 동작할 수 있습니다.
원인 6: 엔터프라이즈 정책 충돌
팀 또는 엔터프라이즈 Claude 플랜을 사용 중이고 관리자가 관리 설정을 배포했다면, 해당 설정은 다음보다 우선합니다.
- 환경 변수
~/.claude/settings.json- 사용자 로컬 설정
관리 정책이 availableModels를 제한하거나 사용자 지정 기본 URL을 차단하면 로컬 설정이 올바르더라도 Invalid custom3p enterprise config가 발생할 수 있습니다.
관리 설정 확인
ls ~/.claude/managed-settings.json 2>/dev/null && echo "Managed settings found"
Claude Code 내부에서는 다음 명령을 사용할 수 있습니다.
/status
Managed settings가 활성화되어 있다면 관리자에게 다음을 요청해야 합니다.
- 게이트웨이 도메인을 허용된 기본 URL에 추가
- 게이트웨이 모델 ID를
availableModels에 추가 - 사용자 지정 기본 URL 제한에서 예외 처리
사용자가 제어하는 엔터프라이즈 배포에서는 관리 설정이 macOS 기준 다음 경로에 있을 수 있습니다.
/Library/Application Support/ClaudeCode/managed-settings.json
Windows/Linux에서는 해당 플랫폼의 Claude Code 관리 설정 경로를 확인하세요.
작동 구성 예시
Claude Code + OpenRouter + DeepSeek V4 Pro
OpenRouter는 Anthropic 호환 API를 제공합니다. 다음 설정은 Claude Code의 에이전트 루프를 DeepSeek V4 Pro로 라우팅합니다.
~/.claude/settings.json:
{
"env": {
"ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
"ANTHROPIC_AUTH_TOKEN": "sk-or-your-openrouter-key",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek/deepseek-v4-pro",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek/deepseek-v4-pro",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek/deepseek-v4-pro"
}
}
모델 오버라이드가 필요한 이유는 Claude Code가 기본적으로 claude-sonnet-4-6 같은 모델명을 사용하기 때문입니다. 기본 URL만 바꾸면 요청이 OpenRouter로 가더라도 모델명은 Claude 모델로 남을 수 있습니다.
OpenRouter의 Anthropic 스트리밍 및 도구 호출 호환성은 업데이트될 수 있으므로 OpenRouter의 Claude Code 통합 문서를 확인하세요.
Claude Code + LiteLLM
LiteLLM은 Claude Code와 함께 쓰기 좋은 게이트웨이입니다. 헤더 전달을 처리하고 여러 공급자 간 모델 라우팅을 지원합니다.
LiteLLM config.yaml:
model_list:
- model_name: claude-sonnet-4-6
litellm_params:
model: deepseek/deepseek-v4
api_key: "sk-your-deepseek-key"
- model_name: claude-opus-4-7
litellm_params:
model: deepseek/deepseek-v4-pro
api_key: "sk-your-deepseek-key"
Claude Code ~/.claude/settings.json:
{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:4000",
"ANTHROPIC_AUTH_TOKEN": "sk-litellm-your-key"
}
}
이 구성에서는 Claude Code가 claude-sonnet-4-6을 요청하면 LiteLLM이 이를 deepseek/deepseek-v4로 라우팅합니다. 따라서 Claude Code 쪽에서 모델명을 직접 바꾸지 않아도 됩니다.
Claude Code + 로컬 vLLM
vLLM으로 로컬 모델을 서빙하려면 Anthropic 호환 모드로 서버를 시작합니다.
python -m vllm.entrypoints.openai.api_server \
--model deepseek-ai/DeepSeek-V3 \
--dtype auto \
--api-key local-key \
--port 8000
Claude Code 설정:
export ANTHROPIC_BASE_URL="http://localhost:8000"
export ANTHROPIC_API_KEY="local-key"
export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-ai/DeepSeek-V3"
디버깅 절차
위 설정을 적용해도 실패한다면 Claude Code를 디버그 모드로 실행합니다.
claude --debug 2>&1 | head -100
출력에서 다음 항목을 확인하세요.
| 로그 항목 | 확인할 내용 |
|---|---|
Sending request to: |
실제 호출 URL |
Response status: |
게이트웨이 HTTP 응답 코드 |
enterprise config error: |
내부 검증 실패 메시지 |
게이트웨이 측에서 동일 요청을 재현하려면 다음 curl을 사용합니다.
curl -v -X POST "${ANTHROPIC_BASE_URL}/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${ANTHROPIC_AUTH_TOKEN}" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: max-tokens-3-5-sonnet-2024-07-15" \
-d '{
"model": "claude-sonnet-4-6",
"max_tokens": 10,
"messages": [{"role": "user", "content": "hi"}]
}'
응답 해석:
-
200: 게이트웨이와 인증이 정상 -
401/403: 인증 문제 -
404: 기본 URL 문제 -
422: 요청 형식 또는 모델 매핑 문제
curl은 성공하지만 Claude Code가 실패한다면, Claude Code가 보내는 preflight 요청과 헤더가 curl과 다를 가능성이 높습니다. --debug 로그를 기준으로 비교하세요.
Apidog로 API 요청 검사하기
타사 공급자 통합을 디버깅할 때 Apidog를 사용하면 LLM 게이트웨이로 전달되는 요청과 응답을 쉽게 검사할 수 있습니다.
게이트웨이의 /v1/messages 엔드포인트에 대한 컬렉션을 만들고 다음 값을 컬렉션 변수로 저장하세요.
ANTHROPIC_BASE_URLAuthorizationanthropic-versionanthropic-beta- 모델명
이렇게 하면 Claude Code를 매번 재실행하지 않고도 OpenRouter, LiteLLM, vLLM 같은 공급자별 응답을 비교할 수 있습니다.
특히 Invalid custom3p enterprise config가 헤더 전달 문제인지 확인할 때 유용합니다. Claude Code 설정을 계속 바꾸기 전에 게이트웨이가 어떤 헤더를 실제로 받고 전달하는지 먼저 검증할 수 있습니다.
알아두면 좋은 Claude Code 설정
베타 헤더 의존성 비활성화
일부 엔터프라이즈 게이트웨이는 사용자 지정 헤더를 전달하지 못합니다.
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
이 설정은 엔터프라이즈 구성 검증에서 베타 기능 핸드셰이크를 제거합니다. 단, 베타 헤더에 의해 활성화되는 일부 기능은 사용할 수 없습니다.
게이트웨이 모델 자동 검색
Claude Code v2.1.129부터 게이트웨이의 /v1/models를 사용해 /model 선택기를 채울 수 있습니다.
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
Claude Code는 시작 시 게이트웨이의 모델 목록을 조회합니다. 단, claude 또는 anthropic으로 시작하는 모델 ID만 자동 추가됩니다. DeepSeek 같은 모델은 여전히 다음처럼 수동 지정이 필요할 수 있습니다.
export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek/deepseek-v4-pro"
사용자 지정 모델 선택기 항목 추가
세션 중 /model 선택기에서 사용자 지정 모델을 고르고 싶다면 다음 변수를 사용할 수 있습니다.
export ANTHROPIC_CUSTOM_MODEL_OPTION="deepseek/deepseek-v4-pro"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="DeepSeek V4 Pro"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Claude Opus보다 17배 저렴"
이 항목은 /model 선택기에 표시되어 기본 Claude 모델과 게이트웨이 모델을 쉽게 전환할 수 있게 해줍니다.
관련 가이드
사용자 지정 모델 백엔드로 Claude Code 에이전트 기능을 실험하고 있다면 다음 글도 참고하세요.
- API 개발 팀을 위한 AGENTS.md 파일 작성 방법 — 특정 스택에 맞게 Claude Code 동작 구성
- Ruflo: Claude Code를 위한 다중 에이전트 오케스트레이션 — Claude Code에 스웜, 영구 메모리, 100개 이상의 MCP 도구 추가
- Puter.js를 통해 무료 무제한 Claude API 이용하기 — 클라이언트 앱을 구축하는 경우 브라우저 기반 대안
- 최고의 로컬 LLM 2026 — vLLM으로 로컬 추론을 실행하려는 경우
자주 묻는 질문
Claude Code에서 타사 공급자를 사용하는 것이 Anthropic 약관 위반인가요?
아닙니다. Anthropic은 Bedrock, Vertex AI, Foundry 및 사용자 지정 게이트웨이를 통한 라우팅을 위해 ANTHROPIC_BASE_URL 패턴을 지원합니다.
2026년 4월 차단된 것은 Claude Code 클라이언트 ID를 위장해 구독 가격으로 Anthropic 자체 API에 접근하던 일부 타사 도구입니다. 자체 게이트웨이나 OpenRouter 같은 공급자를 자신의 API 키로 사용하는 것은 별개의 문제입니다.
Claude Code의 에이전트 루프가 DeepSeek V4 Pro와 작동하나요?
핵심 루프는 작동합니다.
예를 들어 다음 작업은 가능합니다.
- 파일 편집
- 셸 명령 실행
- 다단계 작업 수행
다만 타사 공급자에서는 다음 기능이 제한될 수 있습니다.
- MCP 서버 도구
- 이미지/시각 입력
이 기능이 필요하다면 Anthropic API, Bedrock 또는 Vertex를 계속 사용해야 합니다.
엔터프라이즈 플랜이 아닌데 왜 enterprise config라고 나오나요?
Claude Code는 타사 공급자 설정을 내부적으로 enterprise config라고 부릅니다. 이는 플랜 등급을 의미하는 것이 아니라 코드 수준의 레이블입니다.
개별 개발자도 사용자 지정 타사 공급자를 구성할 수 있습니다.
세션 중 Anthropic과 타사 공급자를 전환할 수 있나요?
단일 세션 내에서는 어렵습니다. 기본 URL은 Claude Code 시작 시 읽힙니다.
전환하려면 다음 순서로 진행하세요.
- Claude Code 종료
- 환경 변수 또는
settings.json변경 - 새 세션 시작
DeepClaude는 이 전환을 --backend ds, --backend anthropic 같은 CLI 플래그로 감싸서 처리합니다.
기업 방화벽 뒤의 게이트웨이를 사용할 수 있나요?
가능합니다. 실행 전에 프록시를 설정하세요.
export HTTPS_PROXY="http://your-proxy:8080"
export ANTHROPIC_BASE_URL="https://your-internal-gateway"
기업 프록시가 TLS를 가로채는 경우 CA 인증서를 추가합니다.
export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca-bundle.pem"
curl 테스트는 성공하는데 Claude Code는 실패합니다. 무엇이 다른가요?
Claude Code는 일반 curl 요청 외에도 사전 검증 요청을 보냅니다. 이 요청에는 다음이 포함될 수 있습니다.
anthropic-betaanthropic-versionX-Claude-Code-Session-Id- 검증용 JSON 본문
claude --debug로 실제 preflight 요청을 확인한 뒤, 해당 헤더와 본문을 curl 테스트에 반영해 비교하세요.
결론
Invalid custom3p enterprise config는 대부분 정책 차단이 아니라 구성 검증 실패입니다.
해결 순서는 다음과 같습니다.
-
ANTHROPIC_BASE_URL에서/v1제거 - 공급자에 맞는 인증 변수 사용
- Bearer 토큰:
ANTHROPIC_AUTH_TOKEN - API 키 헤더:
ANTHROPIC_API_KEY
- Bearer 토큰:
-
~/.claude/settings.jsonJSON 검증 - 새 설치 환경에서 온보딩 플래그 확인
- 게이트웨이 헤더 전달 확인
- 관리 정책 충돌 확인
구성이 정상적으로 검증되면 Claude Code의 에이전트 루프를 OpenRouter, LiteLLM, vLLM 같은 백엔드로 라우팅할 수 있습니다. DeepSeek V4 Pro를 OpenRouter 또는 LiteLLM을 통해 사용하는 구성은 많은 Claude Code 워크플로우에서 비용을 줄이는 대안이 될 수 있습니다. 단, MCP 도구와 시각 입력처럼 Anthropic API가 필요한 기능은 제한될 수 있습니다.

Top comments (0)