콘텐츠로 이동

9.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 가속이 활성화되어 있는지 확인하세요.

관련 페이지