Claude Code

Claude Code는 CC Switch 또는 환경 변수로 HiAPI에 연결할 수 있습니다. 설정 파일을 편집하지 않아도 되는 CC Switch를 권장합니다. HiAPI는 Anthropic Messages 프로토콜을 사용하고 Claude Code는 기본적으로 공식 Anthropic API에 연결되므로, 값 두 개만 바꾸면 전환됩니다. 이 튜토리얼은 Windows 11에서 Claude Code 2.1.284로 검증했으며, 예시 모델로 claude-opus-5-5를 사용합니다.

1. Claude Code 설치

먼저 Node.js(LTS 22.19 이상)를 설치하세요. 아직 없다면 Node.js 설치를 참고하세요. 터미널에서 각 줄을 실행합니다:

npm install -g @anthropic-ai/claude-code
claude --version

버전 번호가 표시되어야 합니다.

2. 방법 1: CC Switch로 원클릭 가져오기(권장)

CC Switch는 설정을 Claude Code에 기록하므로, 나중에 공급자를 바꿀 때 파일을 편집하지 않아도 됩니다. CC Switch가 없다면 CC Switch 설치 및 원클릭 가져오기에 따라 설치하세요.

1. HiAPI 콘솔 → API Keys를 열고 사용할 키를 선택합니다. 키가 없다면 API 키 발급받기에 설명된 대로 만드세요. 여기서는 키를 복사할 필요가 없습니다. 가져오기가 키를 함께 전달합니다.

2. 키 오른쪽의 Import CCS를 클릭합니다(CCS는 CC Switch를 뜻합니다). 브라우저가 CC Switch를 열고 이 공급자 설정을 전달합니다.

3. 가져오기 중에 도구로 Claude Code를 선택한 다음 사용할 모델을 체크합니다.

4. Base URL, API 키, 모델을 확인한 뒤 Import를 클릭합니다. 페이지가 CC Switch로 전환되며 설정이 기록됩니다.

5. CC Switch 메인 창으로 돌아와 HiAPI 항목의 Switch provider를 클릭합니다.

6. 새 터미널을 열고 프로젝트 디렉터리로 이동해 claude를 실행합니다.

3. 방법 2: 환경 변수로 설정

CC Switch를 건너뛸 수도 있습니다. Claude Code는 ANTHROPIC_BASE_URL과 ANTHROPIC_AUTH_TOKEN 두 환경 변수를 읽습니다. Base URL은 /v1 없이 https://api.hiapi.ai로 설정하세요. Claude Code가 경로를 직접 덧붙입니다. 아래 YOUR_HIAPI_API_KEY를 자신의 HiAPI API 키로 바꾸고 따옴표는 유지하세요.

또한 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1을 설정해 Claude Code의 실험적 기능 요청을 끄는 것을 권장합니다. 그러면 서드파티 엔드포인트가 이를 오류로 거부하지 않습니다. CC Switch는 가져오기 시 이 설정을 자동으로 기록합니다.

현재 터미널에만 적용

창을 닫으면 사라집니다. 영구 설정 전 첫 테스트에 적합합니다.

export ANTHROPIC_BASE_URL="https://api.hiapi.ai"
export ANTHROPIC_AUTH_TOKEN="YOUR_HIAPI_API_KEY"
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
claude

$env:ANTHROPIC_BASE_URL = "https://api.hiapi.ai"
$env:ANTHROPIC_AUTH_TOKEN = "YOUR_HIAPI_API_KEY"
$env:CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS = "1"
claude

set "ANTHROPIC_BASE_URL=https://api.hiapi.ai"
set "ANTHROPIC_AUTH_TOKEN=YOUR_HIAPI_API_KEY"
set "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1"
claude

세션 간 유지

Mac은 기본적으로 zsh를 사용합니다. ~/.zshrc에 세 줄을 추가하고(bash는 ~/.bashrc 사용) 다시 로드하세요:

echo 'export ANTHROPIC_BASE_URL="https://api.hiapi.ai"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="YOUR_HIAPI_API_KEY"' >> ~/.zshrc
echo 'export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1' >> ~/.zshrc
source ~/.zshrc

Windows에서는 setx로 사용자 환경 변수에 기록하세요. 터미널을 다시 열면 적용됩니다:

setx ANTHROPIC_BASE_URL "https://api.hiapi.ai"
setx ANTHROPIC_AUTH_TOKEN "YOUR_HIAPI_API_KEY"
setx CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS "1"

4. 확인

프로젝트 디렉터리에서 claude를 실행하고 “안녕하세요, 한 문장으로 자기소개를 해 주세요.”를 보내세요. 정상적으로 답하고 프로젝트 파일을 읽을 수 있다면 연결이 된 것입니다. 추가로 /status를 입력해 Base URL과 모델을 확인하거나, HiAPI 콘솔의 요청 로그에서 이 요청을 찾아보세요.

5. 문제 해결

여기에는 Claude Code에 특화된 문제만 정리했습니다. 401, 404, 429 같은 일반적인 오류는 자주 발생하는 오류를 참고하세요.