Claude Code에서 BeatAPI 사용하기

Claude Code는 터미널에서 파일을 읽고 쓰고, 명령을 실행하며 작업을 처리하는 명령줄 코딩 에이전트입니다. BeatAPI가 POST /v1/messages에서 직접 제공하는 Anthropic Messages 형식을 사용하므로, 변환 계층 없이 기본 URL만 바꾸면 BeatAPI로 연결됩니다.

사전 준비

Claude Code 설치 — 아직 설치하지 않았다면 1단계를 참고하세요.
BeatAPI API 키 — 대시보드 → API Keys에서 만드세요.

1단계: Claude Code 설치

macOS / Linux

Windows

npm

공식 스크립트로 설치합니다.

curl -fsSL https://claude.ai/install.sh | bash

또는 Homebrew로 설치합니다.

brew install --cask claude-code

설치를 확인합니다.

claude --version

2단계: Claude Code를 BeatAPI로 연결

설정 방법은 세 가지이며, 오래 유지되는 순서로 나열했습니다. 하나를 고르세요.

방법 1: settings.json

가장 안정적인 방법입니다. 한 번 설정하면 모든 터미널에서 유지됩니다.

설정 디렉터리를 찾습니다.

macOS / Linux: ~/.claude
Windows: %userprofile%\.claude

디렉터리가 없으면 claude를 한 번 실행하고 Ctrl + C를 눌러 종료하세요. 디렉터리가 자동으로 만들어집니다.

settings.json을 만들거나 편집합니다.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.beatapi.io",
    "ANTHROPIC_AUTH_TOKEN": "<BEATAPI_API_KEY>",
    "ANTHROPIC_MODEL": "claude-fable-5-1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

변수	값
`ANTHROPIC_BASE_URL`	`https://api.beatapi.io` — `/v1` 접미사 없음. 클라이언트가 `/v1/messages`를 덧붙입니다
`ANTHROPIC_AUTH_TOKEN`	BeatAPI API 키
`ANTHROPIC_MODEL`	아래 표의 모델 ID
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	`1`로 백그라운드 요청을 줄입니다

파일을 저장하고 Claude Code를 다시 시작하세요.

방법 2: 영구 환경 변수

macOS (zsh)

Linux (bash)

Windows (PowerShell)

echo 'export ANTHROPIC_BASE_URL="https://api.beatapi.io"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="<BEATAPI_API_KEY>"' >> ~/.zshrc
echo 'export ANTHROPIC_MODEL="claude-fable-5-1"' >> ~/.zshrc
source ~/.zshrc

방법 3: 현재 터미널에서만

빠르게 테스트할 때 유용합니다. 터미널을 닫으면 값이 사라집니다.

export ANTHROPIC_BASE_URL="https://api.beatapi.io"
export ANTHROPIC_AUTH_TOKEN="<BEATAPI_API_KEY>"
export ANTHROPIC_MODEL="claude-fable-5-1"
claude

3단계: 확인하고 작업 시작

claude "Hello"

답변이 오면 설정이 적용된 것입니다. 로그인 화면, 401 또는 403이 나타나면 적용되지 않은 것이니 아래 FAQ를 참고하세요.

Claude Code에는 두 가지 사용 모드가 있습니다.

대화형 — claude를 실행해 세션을 이어 가며, 여러 단계의 작업에 적합합니다.
단발형 — claude "your question"을 실행해 답변 하나만 받습니다.

모델

같은 키로 계정의 모든 Claude 모델을 사용할 수 있습니다. 대화형 세션에서 /model로 전환하거나, ANTHROPIC_MODEL을 바꾸고 다시 시작하세요.

모델 ID	추천 용도
`claude-fable-5-1`	최신 세대. 에이전트 코딩의 기본값
`claude-opus-5`	가장 강력한 추론 등급. 어려운 아키텍처 설계와 디버깅용
`claude-sonnet-5-5`	코딩과 에이전트 워크플로. 1M 컨텍스트, 최대 128K 출력
`claude-sonnet-5`	일상 작업을 위한 성능과 속도의 균형
`claude-haiku-4-5-20251001`	가장 빠르고 저렴함. 간단한 수정과 대량 처리 단계용

모델별 가격은 가격 페이지에, 요청 형식은 Claude API 페이지에 있습니다.

Sonnet 5.5 설정

아래 값을 ~/.claude/settings.json에 병합하고 키 자리 표시자를 바꾼 뒤 Claude Code를 다시 시작하세요.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.beatapi.io",
    "ANTHROPIC_AUTH_TOKEN": "<BEATAPI_API_KEY>",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5"
  }
}

Sonnet 5.5는 기본적으로 적응형 사고를 사용합니다. 사고와 도구 설정은 Claude Code가 관리하도록 두세요. 제한과 현재 토큰 요금은 Sonnet 5.5 모델 가이드를 참고하세요.

자주 쓰는 명령

명령	설명
`claude`	대화형 모드 시작
`claude "question"`	단일 질의
`claude --version`	버전 표시
`/model`	세션 중 모델 전환
`/help`	도움말 표시
`Ctrl + C`	대화형 모드 종료

자주 묻는 질문

설정 후에도 로그인 화면이 나타남

설정이 적용되지 않았습니다.

settings.json을 사용하는 경우 — 경로가 ~/.claude/settings.json(Windows에서는 %userprofile%\.claude\settings.json)인지 확인하세요.
환경 변수를 사용하는 경우 — 변수를 설정한 터미널에서 Claude Code를 실행했는지 확인하세요.
JSON이 올바른지 확인하세요. 중괄호 짝, 마지막 쉼표, 둥근 따옴표 대신 곧은 따옴표를 썼는지 살펴보세요.

401 또는 403

상태	의미	조치
`401`	`missing_api_key` 또는 `invalid_api_key`: 키가 없거나 잘못되었거나 만료, 비활성화, 소진되었습니다	대시보드 → API Keys에서 키가 활성 상태인지 확인하세요
`403`	`forbidden`: 키나 계정이 이 모델을 사용할 수 없습니다(예: 무료 크레딧)	계정 상태와 요청한 모델을 확인하세요

ANTHROPIC_BASE_URL이 모델 제조사의 주소가 아니라 https://api.beatapi.io인지도 확인하세요.

시작할 때 “Auth conflict”가 표시됨

Auth conflict: Both a token (claude.ai) and an API key (ANTHROPIC_API_KEY) are set.

공식 계정에 로그인한 상태에서 API 키도 설정되어 있습니다. Claude Code에서 /logout을 실행해 세션을 지우고 키를 유지하세요.

402 insufficient_credits

잔액 부족: 계정 잔액이 0이거나 요청 가격보다 적습니다. 대시보드에서 충전하세요. 처리 중인 요청은 대기열에 들어가지 않고 실패합니다.

429 rate_limit_exceeded

키의 요청 속도 한도를 넘었습니다. BeatAPI가 Retry-After를 반환하니 그 시간만큼 기다린 뒤 재시도하세요. 분당 한도는 누적 충전액에 따라 올라가며 대시보드에 표시됩니다.

연결 실패

전반적인 네트워크 연결을 확인하세요.
ANTHROPIC_BASE_URL에 오타나 불필요한 /v1이 없는지 다시 확인하세요.
회사 프록시를 사용한다면 api.beatapi.io를 허용하세요.

사용량과 지출 확인

대시보드에서 키별 호출 수, 토큰 사용량, 비용을 볼 수 있습니다. GET /v1/usage에서 프로그래밍 방식으로도 같은 수치를 받을 수 있습니다.

지원

대시보드에서 지원 티켓을 열고 실패한 응답의 request_id를 함께 보내 주세요. 이 값으로 로그에서 해당 호출을 정확히 찾을 수 있습니다.