BroadRouter
시작하기

오픈 모델로 Claude Code 쓰기: 프록시, 네이티브 엔드포인트, 한계

BroadNet Inference 팀 · 6분 분량 · 게시

Claude Code는 Anthropic Messages API 요청을 ANTHROPIC_BASE_URL로 보냅니다. OpenAI 호환 제공업체를 쓰려면 LiteLLM 같은 변환 프록시를 띄우고 Claude Code가 그 프록시를 가리키게 하거나, DeepSeek나 Z.ai처럼 자체 Anthropic 형식 엔드포인트가 있는 제공업체를 고르세요. Anthropic은 Claude Code에서 Claude 외 모델을 지원하지 않으므로 도구, 캐싱, 컨텍스트 한도는 직접 테스트해야 합니다.

Claude Code는 모든 요청을 Anthropic Messages API 형식으로, ANTHROPIC_BASE_URL이 가리키는 곳의 /v1/messages로 보냅니다. BroadNet Inference를 포함한 대부분의 오픈 모델 제공업체는 대신 OpenAI 형식을 씁니다. 따라서 두 형식 사이를 변환하는 프록시가 있거나, 자체 Anthropic 형식 엔드포인트를 공개하는 제공업체를 써야 합니다. 이 글은 두 방법과 함께, 해 볼 가치가 있는지를 가르는 한계도 다룹니다.

Claude Code가 OpenAI 호환 API를 직접 호출할 수 없는 이유는 무엇인가요?

Claude Code의 게이트웨이 호환성 가이드에는 게이트웨이가 노출해야 하는 형식이 나와 있습니다. 일반 base URL이라면 Anthropic Messages, 즉 /v1/messages(선택적으로 /v1/messages/count_tokens)이며, anthropic-beta와 anthropic-version 헤더를 전달해야 합니다. OpenAI 호환 API는 요청과 응답 형태가 다른 /v1/chat/completions를 제공합니다. Claude Code가 이를 바로 가리키면 요청이 실패합니다.

시작하기 전에 알아 둘 것이 하나 더 있습니다. Claude Code 문서에 따르면 Anthropic은 “doesn’t support routing Claude Code to non-Claude models through any gateway.”(번역: 어떤 게이트웨이를 거치든 Claude Code를 Claude 외 모델로 라우팅하는 것은 지원하지 않습니다.) 그래도 많은 사람이 이렇게 쓰지만, Anthropic의 누구도 대신 디버깅해 주지 않습니다.

선택지 세 가지는 무엇인가요?

경로 동작 방식 적합한 경우 단점
변환 프록시(LiteLLM) Claude Code는 로컬 프록시와 Anthropic 형식으로 통신하고, 프록시가 OpenAI 호환 제공업체를 호출 BroadNet처럼 특정 OpenAI 호환 제공업체를 쓸 때 실행하고 업데이트할 프로세스가 하나 늘어남. 변환 누락
네이티브 Anthropic 형식 엔드포인트 제공업체가 /v1/messages를 직접 받음 제작사가 직접 제공하는 DeepSeek나 GLM 모델 업체마다 일부 필드를 매핑하거나 무시함
다른 에이전트 OpenAI 호환 base URL을 받는 에이전트를 씀 꼭 Claude Code가 필요하지는 않은 경우 Claude Code의 인터페이스와 기능을 포기해야 함

LiteLLM으로 Claude Code를 돌리려면 어떻게 하나요?

LiteLLM의 Anthropic 외 모델 튜토리얼은 이렇게 진행됩니다. 프록시를 설치하고, config.yaml에 모델을 정의하고, 실행한 뒤, Claude Code에 변수 두 개를 설정합니다. LiteLLM이 형식을 변환하므로 Claude Code는 계속 Anthropic 요청을 보냅니다.

BroadNet 모델은 LiteLLM 가이드와 같은 방식으로 openai/ 접두사와 api_base를 붙여 정의하세요.

model_list:
  - model_name: glm
    litellm_params:
      model: openai/broadnet/glm-5.3
      api_base: https://inference.broadnet.ai/v1
      api_key: os.environ/BROADNET_API_KEY
      rpm: 30
  - model_name: qwen
    litellm_params:
      model: openai/broadnet/qwen3.8-27b
      api_base: https://inference.broadnet.ai/v1
      api_key: os.environ/BROADNET_API_KEY
      rpm: 30

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

프록시를 실행합니다.

uv tool install 'litellm[proxy]'
export BROADNET_API_KEY='your-broadnet-key'
export LITELLM_MASTER_KEY='sk-any-local-secret'
litellm --config config.yaml   # listens on http://0.0.0.0:4000

그다음 Claude Code가 프록시를 가리키게 합니다. ANTHROPIC_AUTH_TOKEN은 Authorization: Bearer 헤더로 전송되며, LiteLLM은 이 헤더를 읽습니다.

export ANTHROPIC_BASE_URL=http://0.0.0.0:4000
export ANTHROPIC_AUTH_TOKEN="$LITELLM_MASTER_KEY"
export ANTHROPIC_MODEL=glm                  # main model
export ANTHROPIC_DEFAULT_HAIKU_MODEL=qwen   # background tasks
export ANTHROPIC_DEFAULT_SONNET_MODEL=glm   # the sonnet alias
export ANTHROPIC_DEFAULT_OPUS_MODEL=glm     # the opus alias
export CLAUDE_CODE_SUBAGENT_MODEL=glm       # subagents
claude

Claude Code에서 /status를 실행하세요. Anthropic base URL 줄에 프록시 주소가 나와야 합니다.

모델 변수가 중요합니다. LiteLLM의 Claude Code 페이지는 설정에 정의되지 않은 내장 Claude 이름을 고르면 “Invalid model name passed in”(번역: 잘못된 모델 이름이 전달됨) 오류로 실패한다고 경고합니다. Claude Code의 환경 변수 레퍼런스에 따르면 ANTHROPIC_DEFAULT_HAIKU_MODEL은 백그라운드 기능에도 쓰이므로, 이것도 매핑하지 않으면 백그라운드 요청이 프록시가 모르는 Haiku 이름을 요청합니다. CLAUDE_CODE_SUBAGENT_MODEL은 서브에이전트의 기본 모델을 정하지만, Claude가 서브에이전트를 만들 때 넘기는 모델(대개 sonnet이나 haiku 같은 별칭)이 우선합니다. sonnet과 opus 별칭까지 매핑해 두면 이런 요청도 프록시가 아는 모델로 연결됩니다. BroadNet 키는 프록시의 환경에 두고, 프로젝트에 커밋되는 .claude/settings.json에는 절대 넣지 마세요.

프록시 없이 쓸 수 있는 DeepSeek와 GLM 엔드포인트는 무엇인가요?

모델 제작사 두 곳이 Anthropic 형식 base URL을 공개합니다.

제공업체 Base URL 모델 처리 방식(각사 문서, 2026-11-15 확인)
DeepSeek https://api.deepseek.com/anthropic claude-sonnet*과 claude-haiku* 이름은 deepseek-flash로, claude-opus*는 deepseek-v4-pro로 매핑됨. claude로 시작하지 않는 이름은 400 반환
Z.ai(GLM Coding Plan) https://api.z.ai/api/anthropic 키는 ANTHROPIC_AUTH_TOKEN에 넣음. 수동 설정 예시는 Opus와 Sonnet을 glm-5.3[1m]으로, Haiku를 glm-5.3-flash[1m]으로 매핑

DeepSeek의 2026년 9월 10일 릴리스 노트에 따르면 deepseek-flash는 DeepSeek-V4.1-Flash를 제공합니다. DeepSeek의 Anthropic API 페이지에는 무시되는 항목도 나와 있습니다. cache_control, budget_tokens, disable_parallel_tool_use, anthropic-version 헤더 등입니다. deepseek-flash에서는 어시스턴트 메시지에 든 이미지가 400을 반환하고, deepseek-v4-pro는 이미지를 “[Unsupported Image]“로 바꿉니다.

Claude Code에서 DeepSeek나 GLM만 쓰고 싶다면 이 네이티브 엔드포인트가 가장 짧은 길입니다. 두 곳의 가격과 플랜 한도는 Claude API 대안 페이지에서 비교합니다.

Claude 외 모델에서는 무엇이 깨지거나 달라지나요?

변환 덕분에 요청은 계속 흐르지만, Claude Code의 여러 기능은 프록시나 다른 모델이 그대로 전달하지 않을 수 있는 요소에 의존합니다. Claude Code 문서가 꼽는 항목은 다음과 같습니다.

  • 프롬프트 캐싱. Claude Code는 system과 메시지 블록에 cache_control을 표시합니다. 게이트웨이나 업스트림이 이를 버려도 오류는 나지 않지만, 모든 턴이 캐시되지 않은 입력으로 과금됩니다. OpenAI 호환 업스트림에서는 캐싱이 그 제공업체의 자체 규칙을 따릅니다. BroadNet은 usage 블록이 캐시 적중을 보고하면 캐시된 입력을 더 낮은 가격으로 과금합니다. 로그에서 cached_tokens를 확인하세요.
  • 토큰 계산. /v1/messages/count_tokens가 없으면 Claude Code는 글자 수 기반 추정으로 대체하므로 /context는 근삿값이 됩니다.
  • 컨텍스트 윈도. Claude Code는 인식하지 못하는 모델 이름에 자체 기본 윈도를 적용합니다. 모델에 맞게 CLAUDE_CODE_AUTO_COMPACT_WINDOW(100,000~1,000,000 토큰)를 설정하세요. 컨텍스트가 262,144 토큰인 Qwen3.8 27B라면 그보다 넉넉히 낮게 설정하세요.
  • 알 수 없는 필드. Extra inputs are not permitted나 anthropic-beta 값을 언급하는 400은 업스트림 어딘가에서 출시 전 필드를 거부했다는 뜻입니다. 문서는 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1을 권합니다.
  • 사고(thinking). MAX_THINKING_TOKENS와 적응형 사고는 Claude 기능입니다. BroadNet에서 DeepSeek V4.1 Flash, GLM 5.3, Qwen3.8 27B는 답하기 전에 추론하며, 이 추론 토큰은 max_tokens에 포함됩니다. 답변이 비어서 돌아오면 출력 한도를 올리거나 reasoning_effort를 low로 보내세요. 추론 모델이 빈 답변을 반환하는 이유를 보세요.
  • 이미지. BroadNet에서 GLM 5.3은 텍스트 전용입니다. 스크린샷을 붙여 넣는다면 Qwen3.8 27B를 쓰세요.

실제로 의존하기 전에 파일 편집, 셸 명령, 긴 세션을 포함한 실제 작업을 처음부터 끝까지 테스트하세요.

Claude Code 뒤에는 어떤 BroadNet 모델을 둬야 하나요?

Claude Code는 도구 호출로 파일을 읽고 편집하고 명령을 실행합니다. BroadNet API 레퍼런스가 도구, 구조화된 출력, 추론을 문서화한 모델은 두 개입니다.

모델 100만 토큰당 입력 / 출력 컨텍스트 이미지 도구 문서화
GLM 5.3 $0.78 / $3.46 1,048,576 아니요 예
Qwen3.8 27B $0.175 / $2.17 262,144 예 예
DeepSeek V4.1 Flash $0.175 / $0.52 1,048,576 예 문서화되지 않음

큰 저장소라면 GLM 5.3이 자연스러운 주 모델입니다. Qwen3.8 27B는 입력 토큰당 더 싸고, 이미지와 가벼운 백그라운드 호출에 쓸 수 있습니다. 둘 다 충전이 필요하며, $5 상당의 초기 크레딧으로는 쓸 수 없습니다. GLM 5.3 vs Qwen3.8 27B 비교에서 나란히 볼 수 있습니다.

BroadNet 정액 플랜을 Claude Code와 함께 쓸 수 있나요?

문서화된 조합은 아니며, 구매 전에 알아 두는 편이 좋습니다. Full Moon, Orbit, Meteor 플랜은 DeepSeek V4.1 Flash만 지원하는데, BroadNet은 이 모델의 도구 호출을 문서화하지 않습니다. 또한 각 플랜 세션은 한 번에 요청 1개를 처리합니다. Claude Code는 메인 루프와 함께 서브에이전트와 백그라운드 작업을 돌릴 수 있으므로, 이 요청들이 세션 하나에서 줄을 서게 됩니다.

정액 가격을 원한다면 BroadNet이 플랜과 함께 문서화한 Aider 같은 에이전트를 쓰세요. Claude Code에는 종량제 GLM 5.3이나 Qwen3.8 27B를 쓰세요. 키당 분당 30 요청, 동시 요청 4개까지 허용됩니다. 429가 오면 오류와 재시도처럼 백오프하세요.

다른 에이전트가 더 나은 경우는 언제인가요?

Claude Code 자체가 꼭 필요하지 않다면 프록시를 건너뛰세요. opencode, Cline, Roo Code, Continue, Aider는 모두 OpenAI 호환 base URL, 키, 모델 ID를 직접 받습니다. 각 필드 이름은 코딩 에이전트에서 오픈 모델 쓰기에 있고, opencode와 Cline 설정 가이드도 있습니다. 움직이는 부품이 적을수록 변환 버그도 적습니다. 이 작업에 맞는 모델을 비교하려면 코딩 에이전트에 가장 좋은 오픈 모델을 보세요.

확장 사고, Anthropic 프롬프트 캐싱, 최신 Claude Code 베타 같은 Claude 전용 기능에 의존한다면 Claude 모델을 계속 쓰세요. 그 경우 모델을 바꾸기보다 Claude Code 안에서 비용 줄이기를 보세요.

BroadNet Inference의 위치

BroadNet Inference는 OpenAI 호환 API이므로 LiteLLM 같은 프록시를 거쳐야만 Claude Code에 연결됩니다. 프록시 뒤에서는 GLM 5.3과 Qwen3.8 27B가 도구 호출이 문서화된 두 모델이며, 토큰당 과금되고 요청이 끝난 뒤 콘텐츠를 보관하지 않습니다. 네이티브 Anthropic 형식 엔드포인트를 원한다면 DeepSeek와 Z.ai가 더 간단합니다. BroadNet의 정액 플랜을 원한다면 OpenAI 형식을 쓰는 에이전트와 함께 쓰세요.

자주 묻는 질문

Claude Code에서 DeepSeek를 쓸 수 있나요?

네, 두 가지 방법이 있습니다. DeepSeek는 Anthropic 형식 base URL인 https://api.deepseek.com/anthropic을 공개하며, 여기서 claude-sonnet과 claude-haiku 이름은 deepseek-flash로, claude-opus 이름은 deepseek-v4-pro로 매핑됩니다. 또는 DeepSeek 모델을 호스팅하는 OpenAI 호환 제공업체 앞에 LiteLLM 같은 변환 프록시를 둘 수 있습니다.

Claude Code는 OpenAI 호환 API와 함께 동작하나요?

직접은 아닙니다. Claude Code는 Anthropic Messages API 요청을 /v1/messages로 보냅니다. LiteLLM 같은 프록시가 이 요청을 받아 OpenAI 방식의 /chat/completions 엔드포인트로 전달하고, 응답을 다시 변환해 돌려줍니다.

Claude Code를 다른 모델로 쓰는 것을 Anthropic이 지원하나요?

아니요. Claude Code 게이트웨이 문서에 따르면 Anthropic은 어떤 게이트웨이를 거치든 Claude Code를 Claude 외 모델로 라우팅하는 것을 지원하지 않습니다. 실제로는 많은 사람이 쓰고 있지만, 이 경로에서 생기는 버그는 직접 디버깅해야 합니다.

Claude Code 뒤에는 어떤 BroadNet 모델을 써야 하나요?

GLM 5.3 또는 Qwen3.8 27B입니다. BroadNet이 도구 호출을 문서화한 모델은 이 두 개뿐이고, Claude Code는 도구로 파일을 편집하고 명령을 실행합니다. GLM 5.3의 컨텍스트는 1,048,576 토큰이고, Qwen3.8 27B는 262,144 토큰이며 이미지를 받습니다.

BroadNet 무제한 플랜으로 Claude Code를 돌릴 수 있나요?

문서화된 조합은 아닙니다. 정액 플랜은 DeepSeek V4.1 Flash만 지원하는데, BroadNet은 이 모델의 도구 호출을 문서화하지 않습니다. 또한 플랜 세션은 한 번에 요청 1개를 처리하지만, Claude Code는 서브에이전트를 병렬로 돌릴 수 있습니다.

LiteLLM을 거치면 Claude Code가 Invalid model name 오류를 내는 이유는 무엇인가요?

Claude Code가 config.yaml에 정의되지 않은 모델 이름을 요청했기 때문입니다. 대개 내장 Claude 별칭이나 백그라운드용 Haiku 모델입니다. ANTHROPIC_MODEL과 ANTHROPIC_DEFAULT_HAIKU_MODEL을 model_list에 있는 이름으로 설정하세요.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기