Claude Code base URL: ANTHROPIC_BASE_URL 올바르게 설정하기

Wokey Team · 2026-09-24

짧은 답: Claude Code의 base URL은 ANTHROPIC_BASE_URL 환경 변수로 설정합니다. 게이트웨이의 오리진만, /v1 없이 넣으세요. Wokey라면 https://api.wokey.ai이며, /v1/messages는 Claude Code가 직접 붙입니다. 키는 ANTHROPIC_AUTH_TOKEN에 넣으세요. 이 값은 Authorization: Bearer로 전송됩니다. base URL만 설정하고 키를 설정하지 않으면 Claude Code는 저장된 claude.ai 로그인을 계속 사용합니다.

최소 설정

export ANTHROPIC_BASE_URL="https://api.wokey.ai"
export ANTHROPIC_AUTH_TOKEN="your Wokey API key"
claude

Claude Code 안에서 /status를 실행하세요. Status 탭에 다음이 보이면 요청이 Wokey를 거치고 있는 것입니다.

• Anthropic base URL이 https://api.wokey.ai로 설정됨
• ANTHROPIC_AUTH_TOKEN을 가리키는 Auth token 줄

Anthropic base URL 줄이 없다면 변수가 세션에 전달되지 않은 것입니다.

/v1을 붙이면 안 되는 이유

Claude Code는 ANTHROPIC_BASE_URL을 접두사로 취급해 $ANTHROPIC_BASE_URL/v1/messages로 요청합니다. https://api.wokey.ai/v1로 설정하면 요청이 /v1/v1/messages로 가고, Wokey는 다음과 같이 응답합니다.

{"message":"Route POST:/v1/v1/messages not found","error":"Not Found","statusCode":404}

Cursor나 Cherry Studio 같은 OpenAI 호환 클라이언트는 관례적으로 .../v1을 받습니다. Claude Code는 Anthropic의 관례를 따르므로 둘을 섞으면 안 됩니다. /v1/messages나 끝 슬래시도 붙이지 마세요.

AUTH_TOKEN과 API_KEY

Wokey는 두 헤더를 모두 받습니다. 차이는 Claude Code 쪽에 있습니다.

• ANTHROPIC_AUTH_TOKEN은 즉시 적용됩니다.
• ANTHROPIC_API_KEY는 대화형 모드에서 한 번 승인을 받은 뒤에 적용됩니다. 이전에 거부한 키는 조용히 무시됩니다.

두 변수를 서로 다른 값으로 설정하지 마세요. 두 헤더에 서로 다른 키가 들어 있으면 Wokey는 요청을 거부합니다.

{"error":{"code":"conflicting_api_key_headers","message":"conflicting_api_key_headers","type":"invalid_request_error"}}

두 헤더에 같은 키가 들어 있다면 문제없습니다.

base URL만 설정하면 어떻게 되나

base URL은 자격 증명이 아닙니다. ANTHROPIC_BASE_URL만 설정하고 AUTH_TOKEN이나 API_KEY가 없으면, Claude Code는 저장된 claude.ai 로그인으로 요청을 보냅니다. Wokey는 이를 Wokey 키로 인식하지 않고 401을 반환합니다.

게이트웨이 자격 증명을 설정하면 claude.ai 로그인은 저장된 채로 사용되지 않습니다. 다시 쓰려면 변수를 해제하세요.

시작할 때 auth may not work as expected로 끝나는 경고가 보일 수 있습니다. 이전 버전에서는 대신 Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set이라고 표시됩니다. 둘 다 게이트웨이 자격 증명과 저장된 로그인이 함께 있다는 뜻입니다. 게이트웨이만 쓰려면 Claude Code 안에서 /logout을 실행해 저장된 로그인을 지우세요.

settings.json에 영구 설정하기

export는 현재 터미널에서만 유효하며, Dock이나 시작 메뉴에서 실행한 에디터는 이를 보지 못합니다. 평소에 쓰려면 ~/.claude/settings.json의 env 블록에 값을 넣으세요.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.wokey.ai",
    "ANTHROPIC_AUTH_TOKEN": "your Wokey API key"
  }
}

• 셸과 설정 파일이 같은 변수를 설정하면 설정 파일이 우선합니다. 셸 변수를 바꿨는데 효과가 없어 보인다면 먼저 여기를 확인하세요.
• 한 프로젝트에서만 쓰려면 그 프로젝트의 .claude/settings.local.json을 사용하고, gitignore에 포함되어 있는지 확인하세요.
• 키를 프로젝트의 .claude/settings.json에 절대 넣지 마세요. 이 파일은 저장소에 커밋됩니다.

모델 선택

Wokey는 claude-opus-5, claude-sonnet-5, claude-haiku-4-5처럼 Anthropic과 같은 Claude 모델 ID를 사용합니다. 세션 중에는 /model로 바꿀 수 있습니다. Claude Code의 Opus, Sonnet, Haiku 등급별로 어떤 모델을 쓸지 고정하려면 env에 다음을 추가하세요.

{
  "env": {
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

ANTHROPIC_DEFAULT_HAIKU_MODEL은 세션 제목 생성 같은 백그라운드 작업에 쓰이는 모델도 정합니다.

VS Code 확장과 데스크톱 앱

VS Code 확장은 로그인 확인에 셸 변수를 쓰지 않습니다. 대신 VS Code 자체의 사용자 설정에서 지정하세요. 명령 팔레트에서 **Preferences: Open User Settings (JSON)**을 실행하고 다음을 추가합니다.

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://api.wokey.ai" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "your Wokey API key" }
  ]
}

~/.claude/settings.json의 값은 확장이 실행하는 프로세스에는 전달되지만, 확장 자체의 로그인 확인에는 전달되지 않습니다. 확장이 계속 로그인을 요구한다면 위 설정을 사용하세요.

Claude 데스크톱 앱은 ANTHROPIC_BASE_URL도 settings.json도 읽지 않습니다. 게이트웨이를 설정하려면 다음과 같이 하세요.

1. Help → Troubleshooting → Enable Developer Mode를 엽니다.
2. Developer → Configure Third-Party Inference를 열고 게이트웨이 주소를 입력합니다.

전체 단계는 Claude Desktop 설정 가이드를 참고하세요.

먼저 curl로 확인하기

같은 터미널에서 Claude Code를 거치지 않고 테스트합니다.

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

응답으로 알 수 있는 것:

• {"id":"msg_로 시작: URL과 키는 정상이며, 문제는 Claude Code 설정에 있습니다.
• 코드가 invalid_api_key인 401: 키가 없거나, 잘못 입력했거나, 삭제되었습니다.
• /v1/v1/messages가 언급된 404: base URL에 /v1이 하나 더 붙어 있습니다.
• curl은 되는데 Claude Code가 여전히 로그인을 요구: Claude Code 자체에 자격 증명이 없습니다. claude를 실행한 같은 터미널에서 변수를 설정했는지 확인하거나, 변수를 ~/.claude/settings.json으로 옮기세요.