콘텐츠로 이동

Claude Code와 통합하기

Claude Code는 Anthropic의 공식 CLI입니다. Anthropic Messages API를 사용하므로 ANTHROPIC_BASE_URL 환경 변수를 통해 Continuum Router를 포함한 모든 Anthropic 호환 엔드포인트로 지정할 수 있습니다.

이 가이드는 Continuum Router를 통해 제공되는 자체 호스팅 LLM (vLLM, Ollama, llama.cpp, LM Studio, MLxcel, 또는 기타 OpenAI 호환 백엔드)에서 Claude Code를 완전히 작동시키는 과정을 설명합니다. Claude Code가 Anthropic 네이티브 백엔드를 전제로 제공하는 두 기능인 WebFetch와 WebSearch도 포함됩니다.

Claude Code가 기대하는 것

Claude Code는 Anthropic의 호스팅 API를 위해 구축되었습니다. 기본적으로 자체 호스팅 모델이 상위에 있을 때 라우터 측 변환이 필요한 몇 가지 동작을 하드코딩하고 있습니다:

  • /v1/chat/completions이 아닌 /v1/messages (Anthropic Messages 포맷)와 통신합니다.
  • WebFetch의 요약기와 WebSearch의 쿼리 추출기에 대해 작은 haiku급 모델(현재 claude-haiku-4-5-20251001)을 중간 호출합니다.
  • WebSearch 기능은 Anthropic의 네이티브 서버 도구 (web_search_20250305)를 보내고 응답에 server_tool_use + web_search_tool_result 콘텐츠 블록이 포함될 것을 기대합니다.

Continuum Router의 web_search 및 model_aliases 섹션이 구성되어 있으면 세 가지 모두 투명하게 처리됩니다. 아래 라우터 구성을 참조하세요.

사전 요구 사항

시작하기 전에:

  • Continuum Router 설치 (설치 페이지 참조).
  • 라우터에서 접근 가능한 OpenAI 호환 자체 호스팅 LLM 백엔드 최소 하나.
  • WebSearch 기능을 사용하려면 검색 프로바이더 API 키 중 하나: Serper, Brave Search, Exa.
  • 워크스테이션에 Claude Code 설치.

라우터 구성

다음을 수행하는 config.yaml을 작성합니다: (a) 자체 호스팅 백엔드 정의, (b) 선택한 프로바이더로 web_search 활성화, © Claude Code의 하드코딩된 모델 이름이 백엔드로 라우팅되도록 model_aliases 선언.

server:
  bind_address: 0.0.0.0:8000

backends:
  - name: my-self-hosted
    type: vllm                  # 또는 ollama | llamacpp | lmstudio | mlxcel | generic
    url: http://localhost:11434
    api_key: "${BACKEND_API_KEY}"
    models:
      - my-model

web_search:
  enabled: true
  provider: brave               # serper | brave | exa
  api_key: "${BRAVE_API_KEY}"

# Claude Code의 내부 haiku / sonnet / opus 호출을 자체 호스팅 모델에
# 도달하도록 재작성합니다. 이 설정이 없으면 WebFetch와 WebSearch는
# ModelNotFound로 실패합니다.
model_aliases:
  haiku: my-model
  sonnet: my-model
  opus: my-model
  default: my-model

라우터를 시작합니다:

continuum-router --config config.yaml

접근 가능한지 확인:

curl http://localhost:8000/health
# {"status":"ok"}

Claude Code를 라우터로 연결

Claude Code는 상위 Anthropic 호환 API를 선택하기 위해 두 개의 환경 변수를 읽습니다:

  • ANTHROPIC_BASE_URL: Anthropic SDK가 요청을 보낼 베이스 URL. 라우터의 Anthropic 엔드포인트를 가리키도록 설정: http://localhost:8000/anthropic. (/v1/messages 접미사는 SDK가 자동으로 추가합니다.)
  • ANTHROPIC_API_KEY: 라우터에 x-api-key 헤더로 전달됩니다. 라우터의 api_keys 섹션이 허용 모드(permissive)인 경우 비어 있지 않은 값이면 작동하고, 그렇지 않으면 라우터의 api_keys 저장소가 수락하는 키를 사용합니다.

환경 변수가 설정된 상태로 Claude Code를 시작:

export ANTHROPIC_BASE_URL="http://localhost:8000/anthropic"
export ANTHROPIC_API_KEY="dev-key-anything-works-if-permissive"
claude

Claude Code가 메인 대화 턴에 사용하는 기본 모델을 고정하려면 (그렇지 않으면 model_aliases가 어쨌든 재작성할 Claude sonnet 모델 이름으로 기본 설정됨) 다음 중 하나를 설정합니다:

export ANTHROPIC_MODEL="my-model"
# 또는 세션을 명시적으로 시작: `claude --model my-model`

검증

Claude Code 세션 내부에서 세 가지 빠른 검사로 라우터가 추가하는 모든 코드 경로를 커버할 수 있습니다:

메인 대화 턴

> 안녕, 지금 어떤 백엔드와 통신 중이야?

라우터 로그에 하나의 POST /anthropic/v1/messages가 백엔드로 전달되고, 응답은 자체 호스팅 모델에서 나와야 합니다.

WebFetch

> https://www.rust-lang.org/ 를 한 문장으로 요약해줘.

Claude Code는 model: claude-haiku-4-5-20251001로 중간 호출을 실행합니다. 라우터가 Rewrote request.model via model_aliases를 로깅하고 호출을 백엔드로 전달하면, 백엔드가 가져온 페이지를 요약합니다.

WebSearch

> 웹 검색으로 최신 Rust 릴리스를 찾아줘.

Claude Code는 tool_choice를 강제하는 Anthropic 서버 도구 (web_search_20250305)로 중간 요청을 보냅니다. 라우터는:

  1. 한 번의 백엔드 왕복으로 쿼리를 추출합니다,
  2. 구성된 검색 프로바이더를 한 번 호출합니다,
  3. server_tool_use와 web_search_tool_result 콘텐츠 블록을 포함하는 Anthropic 형태의 응답을 반환합니다.

로그에 에뮬레이션 경로가 활성화된 것이 표시됩니다:

INFO  Anthropic web_search server-tool emulation (streaming): extracting query

Claude Code의 WebSearch 패널에 순위가 매겨진 결과가 표시됩니다.

문제 해결

HTTP 422: missing field input_schema

web_search_20250305 지원보다 오래된 라우터 버전을 실행 중입니다. 라우터를 업데이트하세요; 이 수정 사항은 AnthropicTool이 커스텀 및 서버 도구 형태 모두를 수락하도록 완화합니다.

Model claude-haiku-4-5-20251001 not found

model_aliases가 구성되지 않아 Claude Code의 중간 haiku 호출이 도달할 곳이 없습니다. 최소한 백엔드 모델에 매핑되는 default: 항목을 추가하세요.

WebSearch가 결과를 0개 반환함

라우터 로그에서 web_search loop round complete를 확인하세요:

  • 루프가 실행 중이지만 Brave / Serper / Exa가 HTTP 429를 반환하면, 프로바이더의 속도 제한에 걸린 것입니다. 프로바이더의 무료 티어가 낮은 QPS로 제한되어 있을 수 있으니, 플랜을 업그레이드하거나 프로바이더를 전환하세요.
  • Rewrote request.model과 위의 에뮬레이션 로그 라인이 보이지만 결과가 Claude Code에 도달하지 않으면, 프로바이더의 API 키가 유효한지 확인하세요.

Claude Code가 연결에 실패함

확인 사항:

  • ANTHROPIC_BASE_URL이 /anthropic으로 끝나는지 (뒤에 /v1/messages가 붙지 않았는지).
  • 라우터에 접근 가능한지: curl $ANTHROPIC_BASE_URL/v1/messages -H 'content-type: application/json' -d '{"model":"my-model", "max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'
  • 라우터가 API 키 인증을 강제하는 경우, ANTHROPIC_API_KEY가 라우터의 api_keys 저장소에 있는 키인지.

아직 작동하지 않는 것

  • file_id로 Anthropic 호스트 파일을 참조하는 아티팩트 / 첨부 파일: Claude Code의 파일 업로드 흐름은 Anthropic Files API를 통해 라운드트립하며, 라우터는 이를 프록시하지 않습니다. 콘텐츠를 인라인으로 붙여넣거나 라우터의 자체 Files API(/v1/files)를 통해 업로드하세요.
  • Anthropic 측 과금 / 속도 제한 헤더: Claude Code는 때때로 라우터가 내보내지 않는 응답 헤더를 기반으로 Anthropic 특정 할당량 UI를 표시합니다.

참조

  • 웹 검색: web_search 섹션, 프로바이더, 주입 정책, Anthropic 서버 도구 에뮬레이션 경로에 대한 전체 참조.
  • 구성 가이드: 모든 구성 옵션.
  • API 참조: 라우터의 엔드포인트.