콘텐츠로 이동

13.1. Backend.AI GO에서 Claude Code 사용하기

Claude Code는 Anthropic의 공식 CLI 기반 에이전트 코딩 도구입니다. Backend.AI GO의 Continuum Router에 연결하면, 로컬 모델이든 클라우드 모델이든 어떤 모델이든 터미널에서 바로 Claude Code의 백엔드로 사용할 수 있습니다.

작동 원리

API 라우팅 API 라우팅

Continuum Router에는 Anthropic Messages API와 내부 모델 라우팅 간의 양방향 형식 변환을 수행하는 Anthropic API 호환 레이어가 내장되어 있습니다. 덕분에 Claude Code는 별도의 어댑터나 프록시 없이 Backend.AI GO와 직접 통신할 수 있습니다.

graph LR
    A[Claude Code] -->|Anthropic API| B[Continuum Router]
    B -->|라우팅| C[로컬 모델]
    B -->|라우팅| D[클라우드 모델]
  • Claude Code가 Anthropic Messages API 형식으로 요청을 보냅니다.
  • Continuum Router가 /anthropic 엔드포인트에서 요청을 받아 적절한 백엔드 형식으로 변환합니다.
  • 응답은 다시 Anthropic API 형식으로 변환되어 Claude Code에 반환됩니다.

사전 준비

시작하기 전에 다음을 확인하세요:

  • Backend.AI GO가 설치되어 실행 중인 상태
  • Claude Code가 설치된 상태 (npm install -g @anthropic-ai/claude-code)
  • 최소 하나의 모델이 사용 가능한 상태—Backend.AI GO에서 로드된 로컬 모델 또는 설정된 클라우드 제공자

설정 방법

1. TCP 서버 활성화 및 포트 확인

TCP 서버 활성화 대화상자 TCP 서버 활성화 대화상자

Claude Code와 같은 외부 클라이언트가 Continuum Router에 접속하려면, 사이드바의 API 페이지에서 TCP 서버 토글을 활성화하세요. 같은 곳에서 포트도 변경할 수 있습니다. 기본 포트는 38080입니다.

포트 번호

Anthropic 호환 엔드포인트(/anthropic)는 Continuum Router와 동일한 포트(기본 38080)에서 실행됩니다. 이는 포트 8000의 OpenAI 호환 엔드포인트와 별개입니다.

2. Claude Code 연결

두 개의 환경 변수를 설정하여 Claude Code를 로컬 Continuum Router에 연결합니다:

ANTHROPIC_API_KEY="" ANTHROPIC_BASE_URL="http://localhost:38080/anthropic" claude
  • ANTHROPIC_BASE_URL — Continuum Router의 Anthropic 호환 엔드포인트를 가리킵니다.
  • ANTHROPIC_API_KEY — 빈 문자열로 설정합니다. 인증은 Backend.AI GO에서 로컬로 처리되므로 API 키가 필요하지 않습니다.

영구 설정하기

매번 입력하지 않으려면 셸 프로필(~/.bashrc, ~/.zshrc 등)에 환경 변수를 추가하세요:

export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL="http://localhost:38080/anthropic"

3. 모델 선택

--model 플래그를 사용하여 Claude Code가 사용할 모델을 지정합니다. 모델 이름은 Backend.AI GO 인스턴스에서 사용 가능한 모델과 정확히 일치해야 합니다.

ANTHROPIC_API_KEY="" ANTHROPIC_BASE_URL="http://localhost:38080/anthropic" \
  claude --model gpt-5.1

Backend.AI GO의 클라우드 통합 설정에서 구성한 클라우드 모델을 사용합니다.

ANTHROPIC_API_KEY="" ANTHROPIC_BASE_URL="http://localhost:38080/anthropic" \
  claude --model qwen3-coder-next

로컬 모델 라이브러리에서 현재 로드되었거나 사용 가능한 모델을 사용합니다.

활용 시나리오

완전한 프라이버시를 갖춘 오프라인 코딩

Claude Code를 로컬 모델에 연결하면 완전히 오프라인으로 코딩할 수 있습니다. 인터넷이 차단된 환경, 민감한 코드베이스, 또는 데이터가 외부로 나가지 않는 완전한 프라이버시가 필요할 때 이상적입니다.

클라우드 모델 통합 접근

Claude Code에서 각 클라우드 제공자의 API 키를 개별 설정하는 대신, 모든 요청을 Backend.AI GO를 통해 라우팅하세요. Backend.AI GO의 클라우드 통합에서 제공자를 한 번 설정한 후, --model 플래그만 변경하면 어떤 모델이든 사용할 수 있습니다.

모델 간 즉시 전환

로컬 모델과 클라우드 모델 모두 동일한 엔드포인트를 통해 사용 가능하므로, --model 플래그만 변경하면 즉시 전환할 수 있습니다. 환경 변수 재설정이 필요 없습니다.

문제 해결

문제 해결 방법
Connection refused Backend.AI GO가 실행 중이고 API 페이지에서 TCP 서버가 활성화되어 있는지 확인하세요. 포트 번호도 함께 확인하세요.
Model not found 모델 이름이 Backend.AI GO에 표시된 것과 정확히 일치하는지 확인하세요. 로컬 모델의 경우 모델이 로드되어 있는지 확인하세요.
로컬 모델 응답이 느린 경우 로컬 추론 속도는 하드웨어에 따라 다릅니다. 더 작은 모델을 사용하거나 엔진 설정에서 GPU 가속이 활성화되어 있는지 확인하세요.
API Error: 400 Invalid request sent to backend 세션 화면을 열고, 실행 중인 모델의 세션 행을 선택한 후, 진단 탭을 열어 최근 런타임 로그에서 정확한 원인을 확인하세요. 아래 세션 진단 탭으로 400 오류 파악하기를 참조하세요.
런타임 로그에 ...exceeds the available context size... 오류 발생 Claude Code는 기본적으로 약 200K 토큰 컨텍스트 창을 사용합니다. 이에 맞춰 서빙 중인 모델의 컨텍스트 크기를 늘려야 합니다 (예: 200192). 아래 컨텍스트 길이 늘리기를 참조하세요.

세션 진단 탭으로 400 오류 파악하기

Claude Code에서 API Error: 400 Invalid request sent to backend 오류가 발생하면, 오류의 원인은 모델 런타임에 있습니다. 근본 원인을 확인하려면:

실행 중인 모델 세션이 표시된 세션 화면

  1. 사이드바에서 세션 화면을 엽니다.
  2. 실행 중인 모델 세션 행을 클릭하여 상세 드로어를 엽니다.
  3. 드로어에서 진단 탭을 선택합니다.
  4. 최근 런타임 로그를 확인합니다 — 정확한 오류 메시지가 여기에 출력됩니다.

가장 흔한 원인은 아래 섹션에서 설명하는 컨텍스트 크기 불일치입니다.

컨텍스트 길이 늘리기

Claude Code는 기본적으로 약 200K 토큰 컨텍스트 창을 사용합니다. 모델 런타임의 컨텍스트 크기가 이보다 작으면, 창을 채우는 모든 요청이 다음과 같은 메시지와 함께 거부됩니다:

srv send_error: ... exceeds the available context size ...

컨텍스트 크기 초과 오류가 표시된 런타임 로그

컨텍스트 크기를 최소 200192 이상으로 늘린 후 모델을 다시 로드하세요. 아래 두 가지 방법 중 하나를 사용합니다:

모델별 설정 (권장):

  1. 모델 페이지를 엽니다.
  2. 모델 카드의 설정 아이콘을 클릭하여 모델 설정 드로어를 엽니다.
  3. 컨텍스트 탭을 선택합니다.
  4. 컨텍스트 크기를 200192 이상으로 설정합니다.
  5. 모델을 언로드했다가 다시 로드하여 새 값을 적용합니다.

전역 기본값 설정:

  1. 설정 > 생성을 엽니다.
  2. 기본 컨텍스트 길이를 200192 이상으로 설정합니다.
  3. 이 값은 모델별 설정이 없는 모든 모델에 적용됩니다. 모델을 다시 로드하여 적용하세요.

메모리 요구사항

200K 컨텍스트는 일반적인 4K–8K 컨텍스트보다 훨씬 많은 VRAM 또는 RAM이 필요합니다. 모델을 로드하기 전에 하드웨어가 더 큰 창을 수용할 수 있는지 확인하세요.

관련 페이지