8.3. 설정 → Claude Code¶

Claude Code는 Anthropic의 공식 에이전틱 코딩 CLI입니다. Anthropic Messages API를 사용하므로 ANTHROPIC_BASE_URL 환경 변수만 바꾸면 Anthropic 호환 엔드포인트라면 어디든 연결할 수 있고, 여기에는 Backend.AI GO의 Continuum Router도 포함됩니다.

설정 → Claude Code 탭은 Claude Code가 로컬 Backend.AI GO 인스턴스와 통신하는 데 필요한 모든 것을 모아 두는 곳입니다. Anthropic 호스팅 백엔드를 전제로 만들어진 두 기능인 WebFetch와 WebSearch까지 다 포함되죠. 탭은 엔드포인트, 빠른 설정, 모델 별칭, 웹 검색 네 개의 카드로 구성되어 있습니다.

라우터가 노출하는 Anthropic 호환 레이어의 상위 기술 레퍼런스는 Continuum Router & API와 continuum-router의 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 콘텐츠 블록이 포함될 것을 기대합니다.

모델 별칭이 없으면 Claude Code의 haiku급 중간 호출이 Model not found로 실패하고, 메인 대화 턴은 작동하더라도 WebFetch와 WebSearch가 깨집니다. 별칭을 설정하면 이런 내부 모델 이름이 현재 로드된 로컬 모델로 재작성되어, 요약과 검색이 실제 백엔드에 도달합니다.

WebSearch 프로바이더¶

웹 검색 카드는 세 개의 프로바이더를 지원합니다. 가격은 자주 바뀌니, 현재 쿼터는 각 프로바이더 페이지에서 확인하세요.

프로바이더	무료 티어(작성 시점 기준)	가입	추천 용도
Serper	가입 시 2,500 쿼리 무료, 이후 종량제	https://serper.dev/	일반 웹 검색의 기본 선택지, Google 기반 결과
Brave Search	월 2,000 쿼리 무료, 속도 제한 있음	https://api-dashboard.search.brave.com/register	비용에 민감한 개발 작업, 프라이버시 지향 사용
Exa	무료 체험, 이후 유료 플랜	https://dashboard.exa.ai/	기술 콘텐츠 대상의 신경망/시맨틱 검색

위 수치는 어디까지나 작성 시점의 근사치이고, 프로바이더가 자주 바꾸니 링크를 따라가서 직접 확인하는 게 안전합니다.

키 하나, 경로 둘

웹 검색 카드는 기본적으로 키를 직접 입력하도록 되어 있지만, '설정 → Serper Search / Brave Search에 저장된 키 사용' 라디오 옵션도 제공합니다. 이 옵션을 고르면 같은 API 키를 두 곳에 따로 넣지 않아도 되고, 값은 설정 → Serper Search(또는 Brave Search)에서 관리하면서 Claude Code 경로가 그 값을 그대로 가져다 쓰는 식이 됩니다.

공유 키 옵션을 선택했을 때 router_config.yaml에 실제로 저장되는 값은 ${BACKEND_AI_SERPER_API_KEY} 또는 ${BACKEND_AI_BRAVE_API_KEY}라는 안정적인 플레이스홀더 문자열입니다. continuum-router는 설정을 읽을 때 일반적인 ${ENV_VAR} 확장 메커니즘으로 이 플레이스홀더를 해석하고, Backend.AI GO는 라우터 자식 프로세스를 띄울 때마다 설정 → Serper Search가 기록하는 것과 같은 SecureKeyStorage 키체인 항목에서 값을 읽어 해당 환경 변수로 주입합니다. 평문 키는 router_config.yaml에 절대 기록되지 않습니다.

설정 → Serper Search(또는 Brave Search)에서 키를 교체하면 실행 중인 라우터가 자동으로 재시작되므로 Claude Code 탭을 다시 만질 필요가 없습니다. Exa는 이 경로에 들어가지 않는데, 설정 → Exa Search 패널이 아직 없어서 여기서 수동 입력만 가능합니다. 이 통합 작업의 진행 상황은 이슈 #2940에서 따라갈 수 있습니다.

세 가지 환경 변수¶

Claude Code는 요청을 어디로 보낼지 결정하기 위해 세 개의 환경 변수를 읽습니다. 엔드포인트 카드는 세 변수를 모두 노출하고, export 형식과 .env 형식 복사 단축 버튼을 제공해서 셸에 붙여넣을 값이 라우터가 받아들이는 값과 정확히 일치하도록 합니다.

ANTHROPIC_BASE_URL — Anthropic SDK가 요청을 보낼 베이스 URL입니다. 엔드포인트 카드는 라우터의 TCP 바인드에서 이 값을 도출하는데, 와일드카드 바인드(0.0.0.0, [::])는 로컬 Claude Code 사용을 위해 127.0.0.1로 재작성됩니다. 그래야 실수로 잘못된 네트워크 인터페이스를 가리키지 않거든요. /v1/messages 접미사는 SDK가 알아서 붙이므로 여기 값은 /anthropic으로 끝납니다.

ANTHROPIC_API_KEY — 라우터에 x-api-key 헤더로 전달됩니다. 라우터가 허용 모드(키가 구성되지 않은 상태)이면 비어 있지 않은 모든 값이 받아들여지고, 여기에는 dev-key도 포함됩니다. 그렇지 않다면 설정 → API → 키에서 발급한 키를 붙여넣으세요. 키를 만들 때 표시된 원본 값만 여기서 사용할 수 있고, 분실하면 새로 만들어야 합니다.

ANTHROPIC_MODEL — 선택 사항. Claude Code의 메인 대화 턴은 내부적으로 sonnet급 이름을 기본값으로 사용하는데, ANTHROPIC_MODEL을 설정하면 그 턴이 현재 로드된 특정 로컬 모델로 고정됩니다. 메인 답변을 별칭 재작성 경로 대신 특정 가중치 클래스에서 받고 싶을 때 유용합니다.

단계별 워크스루¶

로컬 모델 로드. 모델 탭을 열고 모델을 다운로드하거나 선택한 다음(첫 검증에는 Qwen2.5-1.5B 같은 작은 모델이면 충분합니다) 로드를 클릭합니다.
설정 → Claude Code 열기. 엔드포인트 카드에는 실행 중인 라우터에서 도출된 비어 있지 않은 ANTHROPIC_BASE_URL이 표시되고, 모델 별칭 카드에는 네 개의 기본 슬롯(haiku, sonnet, opus, default)이 비어 있는 상태로 보입니다.
빠른 설정. 빠른 설정 카드에서 방금 로드한 모델을 선택하고 적용을 클릭하면, 모델 별칭 카드에 그 모델 이름이 haiku / sonnet / opus / default 모두에 들어갑니다. 디스크의 라우터 설정 파일에는 새로운 model_aliases: 블록이 추가되고, 라우터가 핫 리로드됩니다.
확인. 엔드포인트 카드의 확인을 클릭하면 작은 POST /anthropic/v1/messages 한 번을 라우터에 보내고, 약 2초 안에 연결됨과 라우터가 응답한 모델 이름을 보여줍니다. 실패한다면 아래 문제 해결을 참고하세요.
export로 복사. 엔드포인트 카드의 export 형식으로 복사를 클릭해서 결과를 터미널에 붙여넣은 다음 claude(또는 claude --model <이름>)를 실행합니다. 안녕이라고 보내고 로컬 백엔드 로그에 요청이 찍히는지 확인합니다.
WebFetch 시도. Claude Code 세션에서 https://www.rust-lang.org/ 를 한 문장으로 요약해줘라고 보냅니다. 라우터 로그에 haiku급 내부 호출에 대한 Rewrote request.model via model_aliases가 찍히고, 요약은 로컬 모델에서 옵니다.
웹 검색 활성화. 탭으로 돌아와서 웹 검색을 켜고 프로바이더를 선택합니다(무료 티어가 가장 쉬운 Serper나 Brave가 시작용으로 적당합니다). 그 다음에는 API 키를 직접 입력해도 되고, 설정 → Serper Search / Brave Search에 저장된 키 사용을 골라 이미 저장해 둔 값을 재사용해도 됩니다. 환경 변수에서 읽고 싶으면 ${SOME_ENV_VAR} 형식의 사용자 지정 플레이스홀더를 붙여넣어도 됩니다. 저장합니다.
WebSearch 시도. 같은 Claude Code 세션에서 웹 검색으로 최신 Rust 릴리스를 찾아줘라고 보냅니다. 라우터 로그에 Anthropic web_search server-tool emulation: extracting query가 찍히고, Claude Code의 WebSearch 패널에 순위가 매겨진 결과가 표시됩니다.

위 스크린샷 자리는 이슈 #2928의 수동 검증 단계에서 실제 캡처로 교체될 예정입니다.

문제 해결¶

표의 각 오류는 엔드포인트 카드의 확인 프로브가 노출하는 힌트와 1:1로 대응하므로, 문서와 UI가 같은 것을 가리킵니다.

보이는 메시지	의미	해결 방법
`Connection refused`(확인)	표시된 주소에서 라우터 프로세스가 실행되고 있지 않음	설정 → API → 상태를 확인하고 라우터를 재시작하세요. 라우터 설정에서 포트가 덮어써지지 않았는지도 확인합니다.
`Request timed out after 5 s`(확인)	라우터가 1토큰 프로브에 응답하기까지 너무 오래 걸림	로드된 모델이 LRU에서 빠진 경우가 흔하니, 다시 로드하세요. CPU/GPU 부하도 확인합니다.
`Authentication failed`(확인)	`ANTHROPIC_API_KEY`가 라우터의 `api_keys` 저장소에 없음	설정 → API → 키에서 새 키를 만들고, 일회성으로 표시되는 원본 값을 여기에 붙여넣으세요.
`Model not found`(확인)	라우터는 프로브를 전달하지만 일치하는 백엔드 모델이 없음	모델 별칭 카드에서 default 별칭을 설정하거나(또는 빠른 설정 사용), 모델이 실제로 로드되었는지 확인하세요.
`Router could not parse the request`(확인)	라우터가 Claude Code의 스키마를 이해하지 못함	continuum-router를 v1.6.1 이상(이 Backend.AI GO 빌드에 포함된 버전)으로 업그레이드하세요.
`Model claude-haiku-4-5-20251001 not found`(`claude` 로그)	확인의 'Model not found' 힌트와 같은 근본 원인이지만 haiku급 중간 호출에서 발생	모델 별칭 카드의 haiku 슬롯이나 default 슬롯을 설정하세요.
WebSearch가 결과를 0개 반환	프로바이더 속도 제한에 걸렸거나 API 키가 유효하지 않음	라우터 로그에서 `web_search loop round complete`와 프로바이더 응답 코드를 확인하세요. 무료 티어의 HTTP 429인 경우가 가장 흔하니 플랜을 업그레이드하거나 프로바이더를 바꿉니다.
`HTTP 422: missing field input_schema`	continuum-router가 `web_search_20250305` 지원 이전 버전	continuum-router를 업그레이드하세요. Backend.AI GO는 번들된 라우터 버전을 고정하므로, 바이너리를 수동으로 교체한 경우에만 이 오류가 발생합니다.

공유 키 환경 변수 (고급)¶

저장된 키 옵션을 선택하면 router_config.yaml에 ${BACKEND_AI_SERPER_API_KEY} 또는 ${BACKEND_AI_BRAVE_API_KEY} 플레이스홀더가 기록됩니다. 이 변수 이름은 안정적이라 외부에서 직접 주입해도 동일하게 동작합니다.

프로바이더	YAML 플레이스홀더	환경 변수 이름	해석 방식
Serper	`${BACKEND_AI_SERPER_API_KEY}`	`BACKEND_AI_SERPER_API_KEY`	Backend.AI GO가 라우터를 띄울 때 `SecureKeyStorage`의 `serper_api_key`를 읽어 라우터 프로세스에 주입
Brave Search	`${BACKEND_AI_BRAVE_API_KEY}`	`BACKEND_AI_BRAVE_API_KEY`	Serper와 동일하게 `SecureKeyStorage`의 `brave_search_api_key`를 사용

Backend.AI GO를 띄우기 전 셸에서 직접 환경 변수를 설정하거나 서비스 매니저 유닛 파일로 넘겨주는 식으로 외부에서 값을 줘도, 키체인에 저장된 값과 동일한 경로를 탑니다. 라우터는 값의 출처와 관계없이 프로세스 환경에서 ${BACKEND_AI_*_API_KEY}를 해석합니다.

설정 → Serper Search나 설정 → Brave Search에서 키를 갱신하면 라우터 자식 프로세스가 자동으로 재시작되어 새 값을 반영하므로, Backend.AI GO 자체를 다시 실행할 필요는 없습니다.

작동하지 않는 것¶

Anthropic 호환 레이어는 변환 심(shim)이지 Anthropic 호스팅 제품의 완전한 재구현이 아닙니다. 다음 Claude Code 기능은 범위 밖입니다.

Anthropic Files API / 아티팩트의 file_id 기반 호스팅 파일 참조. Claude Code의 파일 업로드 흐름은 Anthropic Files API를 통해 라운드트립하는데, 라우터는 이를 프록시하지 않습니다. 콘텐츠를 인라인으로 붙여넣거나 라우터 자체의 /v1/files 엔드포인트로 업로드하세요.
Anthropic 측 과금 / 쿼터 / 속도 제한 헤더. Claude Code는 라우터가 내보내지 않는 응답 헤더(anthropic-organization-id, anthropic-ratelimit-*)를 기반으로 Anthropic 특정 쿼터 UI를 표시할 때가 있습니다. CLI 자체는 정상 작동하지만 그 패널은 비어 있습니다.