Claude Code API 설정: 키, settings.json, 모델, 게이트웨이 확인 순서

Claude Code에 발급받은 Anthropic API 키를 연결하려면 Claude Code를 실행할 터미널에 ANTHROPIC_API_KEY를 설정한 뒤 claude를 시작합니다. 대화형 실행에서는 키 사용 승인 여부를 확인해야 합니다. 다른 공급자나 우선하는 인증이 없는 일반 CLI에서 claude -p는 키가 있으면 사용하므로, 대화형 실행에서 구독 로그인을 골랐다고 자동화 실행까지 같은 결제 경로가 되는 것은 아닙니다. 이 동작은 현재 공식 인증 문서를 기준으로 합니다.

이미 설정했는데도 원하는 키나 모델이 적용되지 않는다면 파일부터 덮어쓰지 마세요. 먼저 이번 실행이 API 키, 저장된 로그인, 게이트웨이, 클라우드 공급자 중 무엇을 사용하는지 확인하고, 그다음 설정 범위와 모델을 맞추면 됩니다. 아래 예시는 문서에 따른 설정 방법이며 실제 계정에서 API를 호출해 얻은 결과는 아닙니다.

활성 경로부터 정하기

API 키가 모든 사용 방식에 필요한 것은 아닙니다. Claude Code v2.1.242부터는 API 키를 새로 만들지 않고 Console에 로그인하는 방식도 지원합니다. 다만 이 전환은 ANTHROPIC_API_KEY를 해제하고 저장된 claude.ai 로그인에서 나오는 절차를 수반합니다. 이미 사용 중인 계정을 유지하려는 사람에게 단순한 설정 파일 수정처럼 안내할 수는 없습니다. 조직의 로그인 정책도 적용되므로 인증 방식별 조건을 먼저 확인하세요.

발급받은 API 키로 실행하기

아래는 Bash에서 키를 화면에 표시하거나 명령 기록에 직접 남기지 않고 입력하는 예시입니다. macOS·Linux에서 Bash를 사용하는 경우에 해당합니다. Bedrock 등 다른 공급자를 선택한 상태나 조직이 강제한 게이트웨이 환경에는 이 직접 API 절차를 그대로 적용하지 않습니다. 기존 ANTHROPIC_AUTH_TOKEN이나 별도 ANTHROPIC_BASE_URL이 있다면 아래 인증·게이트웨이 항목에서 의도한 연결인지 먼저 확인합니다.

IFS= read -r -s -p 'Anthropic API key: ' ANTHROPIC_API_KEY
printf '\n'
export ANTHROPIC_API_KEY
claude

1. 사용할 키를 입력하고 Enter를 누릅니다. 입력 중 키가 보이지 않는 것이 정상입니다.
2. Claude Code가 이 키를 사용할지 묻는다면 API 사용이 목적일 때 승인합니다. 이 대화형 선택은 기억되며, 이후 터미널의 /config에서 Use custom API key 항목으로 바꿀 수 있습니다.
3. Claude Code 안에서 /status를 열어 인증 방식과 공급자 표시를 확인합니다. API 키가 설정돼 있어도 사용하지 않는 상태라면 현재 선택과 다른 활성 인증을 살펴봅니다.
4. 연결을 실제로 확인하려면 짧은 메시지 하나를 보냅니다. 정상적인 모델 답변이 오면 그 요청의 추론 연결이 확인된 것입니다. 실제 요청은 API 사용량과 비용을 발생시킬 수 있습니다.

이 입력 방식의 변수는 현재 터미널과 그 자식 프로세스에 전달됩니다. 새 터미널이나 Dock에서 실행한 편집기에 자동으로 이어지지 않습니다. 반복 사용은 자신의 비밀 관리 도구 또는 적절한 개인 설정으로 관리하되, 키를 공유 프로젝트 파일에 넣지 마세요.

Windows도 변수 이름은 ANTHROPIC_API_KEY입니다. PowerShell에서 실행한다면 그 PowerShell 프로세스의 환경에 키가 전달돼 있어야 합니다. WSL 터미널에 설정한 키가 Windows에서 별도로 실행한 VS Code까지 전달된다고 가정하면 안 됩니다. 값 자체를 출력할 필요 없이 PowerShell에서는 다음처럼 유무만 확인할 수 있습니다.

if ($env:ANTHROPIC_API_KEY) { 'ANTHROPIC_API_KEY: 설정됨' }
else { 'ANTHROPIC_API_KEY: 없음' }

비대화형 실행의 예시는 다음과 같습니다. 앞서 키를 전달한 같은 터미널에서 실행하며, 실제 API 요청이라는 점은 같습니다.

claude -p '한 문장으로 답해 주세요: 연결 확인'

-p는 대화형 키 승인 선택에 기대어 구독 경로를 유지하지 않습니다. API 키가 있을 때 사용하는 동작과 우선하는 인증·조직 정책·별도 공급자 설정의 예외를 함께 확인해야 합니다. 공식 인증 설명

credentials 우선순위

인증 충돌을 풀 때는 환경 변수의 이름만 세는 것보다 현재 공급자와 실제로 선택된 인증을 확인하는 편이 정확합니다. 일반적인 로컬 CLI의 인증 후보는 아래와 같지만, 모든 앱과 조직을 한 줄 순위로 설명할 수는 없습니다.

로그인된 Claude 앱 게이트웨이는 별도 인증 경로로 다른 공급자보다 우선할 수 있습니다. 또한 조직의 forceLoginMethod, forceLoginOrgUUID, allowedProviders 같은 정책이 특정 인증이나 공급자를 제한할 수 있습니다. 환경 변수를 바꾸는 것으로 관리 정책을 우회하려고 하지 말고 관리자에게 허용된 연결 방식을 확인하세요. 현재 인증 선택 규칙

ANTHROPIC_AUTH_TOKEN과 apiKeyHelper가 함께 설정됐다는 경고를 받았다면, 사용하려는 게이트웨이가 어느 인증 방식을 요구하는지부터 확인합니다. Bearer 토큰을 쓸 계획이면 불필요한 helper 설정을 해당 설정 범위에서 제거하고, helper를 쓸 계획이면 불필요한 AUTH_TOKEN을 제공하는 위치에서 제거합니다. 파일을 통째로 지우거나 helper를 시험 삼아 실행하는 방식으로 해결할 필요는 없습니다.

셸에서 키를 확인할 때 echo $ANTHROPIC_API_KEY로 비밀값을 출력하지 마세요. 아래 Bash 코드는 설정 여부만 보여 줍니다. settings 파일이나 편집기가 별도로 전달한 변수까지 확인하는 명령은 아닙니다.

for name in ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN CLAUDE_CODE_OAUTH_TOKEN; do
  if [[ -n "${!name}" ]]; then
    printf '%s: 설정됨\n' "$name"
  else
    printf '%s: 없음\n' "$name"
  fi
done

settings.json 범위

개인 기본 설정은 ~/.claude/settings.json, 프로젝트 공유 설정은 .claude/settings.json, 개인 프로젝트 설정은 .claude/settings.local.json에 둡니다. 설치 직후 이 파일이 없을 수도 있습니다. 세 파일을 모두 만들어야 하는 것은 아닙니다. 공식 설정 문서

동일한 설정이 충돌하면 기본 범위 순서는 관리형 → 실행 인수 → 프로젝트 로컬 → 프로젝트 공유 → 사용자입니다. 다만 이것을 “위쪽 JSON 파일이 아래쪽 파일 전체를 덮어쓴다”는 뜻으로 읽으면 안 됩니다. 목록은 합쳐질 수 있고 일부 보안 항목과 모델 관련 목록에는 별도 규칙이 있습니다.

API 키와 URL은 env 블록에 넣을 수 있나요?

가능합니다. env 블록으로 Claude Code 프로세스에 환경 변수를 전달할 수 있습니다. apiKey 같은 임의의 최상위 항목을 만드는 대신 정확한 환경 변수 이름을 사용합니다. 아래는 형식을 보여 주는 자리표시자 예시입니다. 실제 사용 시 값 교체가 필요하며 파일 전체를 기존 파일 위에 덮어쓰지 말고 필요한 항목만 합칩니다.

{
  "env": {
    "ANTHROPIC_API_KEY": "REPLACE_WITH_YOUR_ANTHROPIC_API_KEY"
  }
}

실제 키가 들어간 파일은 개인용으로 관리해야 합니다. .claude/settings.local.json은 Claude Code가 만들면 Git에서 무시되지만, 직접 만들었다면 무시 설정을 확인해야 합니다. 이미 추적 중인 파일은 이름에 local이 붙는다고 비공개가 되지 않으며, Git 제외만으로 비밀값이 암호화되는 것도 아닙니다. 공유 .claude/settings.json에 실제 키를 넣지 마세요.

env는 별도의 우선순위 단계가 아닙니다. 먼저 설정 범위에 따라 env의 각 변수 값이 결정됩니다. 같은 변수가 셸과 settings의 env에 모두 있으면 settings 값이 적용됩니다. 그래서 터미널의 키만 바꿨는데도 이전 설정이 계속 쓰일 수 있습니다. 게이트웨이 연결 문서의 환경 변수 적용 설명

파일을 고쳤는데 적용되지 않을 때

JSON은 주석과 마지막 쉼표가 없는 엄격한 형식이어야 합니다. /status에 설정 파일이 보이는 것은 그 파일이 읽혔다는 단서이며 모든 항목의 최종값과 출처를 증명하지는 않습니다. 터미널의 /config도 전체 JSON을 펼쳐 보는 기능이 아닙니다.

프로젝트 공유 env에는 작업 공간 신뢰 여부가 영향을 줍니다. Git worktree의 로컬 설정이 항상 각 폴더에서 독립적으로 읽힌다고 가정하지 마세요. Git 저장소에서는 기본적으로 루트·기본 worktree의 로컬 설정이 사용되는 조건이 있습니다. 실제 읽힌 위치를 확인하는 것이 먼저입니다.

대부분의 설정은 변경을 감지해 다시 읽지만 모델과 effort는 시작 시 읽습니다. 모델은 실행 중 /model로 바꾸거나 새 실행에서 확인합니다. 무조건 파일을 삭제하고 재로그인할 이유는 없습니다. 설정의 범위·신뢰·변경 적용 규칙

API 키와 게이트웨이

이미 사용 중인 게이트웨이에 연결하려면 주소, 인증 방식, 지원 모델 ID가 모두 필요합니다. ANTHROPIC_BASE_URL에 주소만 넣는 것으로 API 인증이나 결제 경로가 자동으로 바뀌지 않습니다. 별도 게이트웨이 인증이 없으면 저장된 OAuth 로그인을 계속 사용할 수 있고, 게이트웨이에도 그 인증 요청을 처리하는 기능이 필요합니다. 게이트웨이의 인증과 결제 관계

Bearer 토큰을 요구하는 Messages 형식 게이트웨이의 Bash 예시는 다음과 같습니다. 주소와 모델은 사용 중인 서비스가 제공한 값으로 바꿉니다. 이 예시는 기존 공급자 선택이나 조직의 강제 설정이 없는 일반 로컬 연결을 전제로 합니다.

export ANTHROPIC_BASE_URL='https://gateway.example.com'
IFS= read -r -s -p 'Gateway bearer token: ' ANTHROPIC_AUTH_TOKEN
printf '\n'
export ANTHROPIC_AUTH_TOKEN
claude --model 'REPLACE_WITH_GATEWAY_MODEL_ID'

게이트웨이가 x-api-key를 요구한다면 ANTHROPIC_AUTH_TOKEN 대신 ANTHROPIC_API_KEY를 사용합니다. apiKeyHelper는 두 인증 헤더를 모두 보내므로 어떤 방식을 쓸지는 게이트웨이 문서와 맞춰야 합니다. 주소 변경과 함께 저장된 로그인부터 삭제하는 절차는 필수가 아닙니다. 인증 헤더와 연결 설정

“OpenAI 호환 API”라는 설명만으로 Claude Code 호환성을 판단하지 마세요. Messages 형식이라면 /v1/messages와 필요한 anthropic-version, anthropic-beta 헤더가 맞게 전달돼야 합니다. 특히 beta 헤더는 현재 값을 그대로 전달해야 하며 예전 이름만 허용하는 방식은 새 기능을 막을 수 있습니다. Bedrock Invoke나 Google Cloud 형식으로 연결한다면 해당 형식과 공급자 선택 설정이 필요합니다. 주소가 열리거나 준비용 요청이 응답한 것만으로 실제 추론이 성공한 것은 아닙니다. 게이트웨이 프로토콜 요구 사항

연결한 경로에서 system, developer, tool 역할을 거부하는 400이 나온다면 시스템 지시와 도구 기록을 보존하는 역할 오류 해결 방법을 확인하세요.

모델과 제공자 경로

요청 주소와 모델 이름은 서로 다른 설정입니다. ANTHROPIC_BASE_URL을 바꿔도 모델 ID가 그 서비스에 맞게 자동 변환되지는 않습니다. 직접 API에서는 지원되는 모델 ID, Bedrock에서는 사용 가능한 추론 프로필 ID·ARN, Foundry에서는 실제 배포 이름처럼 공급자가 받는 값을 사용합니다. 공식 모델 설정

/model은 현재 세션만 바꾸나요?

현재 동작에서는 /model에서 Enter로 고르거나 이름을 직접 지정하면 사용자 기본값도 저장합니다. 현재 세션만 바꾸려면 모델 선택 화면에서 s를 사용합니다. --model과 ANTHROPIC_MODEL은 시작 시 모델을 지정하는 방식입니다. 이전의 “/model은 항상 이번 세션에만 적용된다”는 설명을 따르지 마세요. 모델 선택과 기본값 저장

현재 세션의 /model 선택을 제외한 시작 모델은 --model → ANTHROPIC_MODEL → settings의 model → ANTHROPIC_DEFAULT_MODEL 순으로 확인합니다. 예를 들어 settings에 "model": "sonnet"이 있어도 실행할 때 --model을 주면 그 시작 값이 앞섭니다. ANTHROPIC_DEFAULT_MODEL은 가장 낮은 기본값이며 모델 계열별 매핑 변수와는 다릅니다.

default는 특정 모델의 고정 이름이 아니라 재정의를 해제하고 계정·공급자에 맞는 기본값을 사용하는 선택입니다. 별칭이 가리키는 모델은 공급자와 버전에 따라 달라질 수 있습니다. 재현 가능한 설정이 필요하다면 제공자가 확인해 준 정확한 ID를 고정하세요. 조직의 availableModels 제한도 확인해야 합니다.

Bedrock, Google Cloud, Foundry의 최소 설정

아래는 이미 자격 증명과 모델 권한이 준비된 환경의 필수 연결 항목입니다. 계정 생성이나 IAM 권한 부여를 대신하는 절차가 아닙니다.

각 값은 Bedrock, Google Cloud, Foundry의 현재 설정 문서와 맞추세요. 리전과 모델의 실제 제공 여부는 계정에서 확인해야 합니다. Foundry 인증은 지원 버전에서 ANTHROPIC_FOUNDRY_AUTH_TOKEN → ANTHROPIC_FOUNDRY_API_KEY → Azure SDK 기본 인증 순으로 선택됩니다. Foundry는 시작 시 모델 확인을 하지 않으므로 첫 요청에서 배포 이름 오류가 드러날 수 있습니다.

Bedrock 경로를 확인했는데 400이 계속 나면 AWS Bedrock Claude 400의 메시지별 해결로 오류 원문을 구분하세요. 같은 상태 코드라도 요청 형식, 모델, 리전, 권한 중 고칠 곳이 다릅니다.

VS Code와 Desktop에서도 같은 설정을 쓰나요?

터미널에서 성공한 설정이 모든 앱에 전달되는 것은 아닙니다. 셸의 환경 변수는 그 셸에서 시작한 자식 프로세스에 전달됩니다. Dock·시작 메뉴에서 별도로 연 편집기나 서버 프로세스에는 전달되지 않을 수 있습니다.

VS Code 확장은 확장 자체의 사전 인증 확인과 실제로 실행한 Claude Code 프로세스를 구분합니다. ~/.claude/settings.json의 env는 실행된 프로세스에 전달되지만 확장의 사전 인증 확인까지 해결하지는 않습니다. 필요한 경우 VS Code 사용자 설정의 claudeCode.environmentVariables에 해당 환경을 전달해야 합니다. API 키와 게이트웨이 토큰을 팀의 공유 편집기 설정에 넣지 마세요.

Desktop은 일반 셸의 ANTHROPIC_BASE_URL이나 CLI settings 파일을 그대로 사용하는 방식이 아니라 Third-party inference 설정을 사용합니다. 관리형 설정이 있으면 그것이 우선하고, 이 로컬 게이트웨이 설정을 SSH·Cloud·Remote Control 세션까지 확대해서 적용할 수는 없습니다. Claude Code의 Cloud 세션도 로컬 CLI의 API 키·토큰 변수로 구독 인증을 덮어쓰는 환경이 아닙니다. 앱별 게이트웨이 설정, 인증 적용 범위

검증 루프

설정 파일이 유효한 것과 원하는 경로로 실제 요청이 성공한 것은 다른 확인입니다. 다음 순서로 확인하면 어디까지 해결됐는지 구분할 수 있습니다.

401이나 404를 받았다는 사실만으로 키가 유효하거나 모델 호출이 성공했다고 결론 내리면 안 됩니다. 게이트웨이마다 인증과 모델 확인 순서가 다릅니다. 오류 원문, 요청 주소, 모델 ID, 요청 ID를 함께 확인하되 키와 토큰은 공유하지 마세요. /status만 보고 실제 사용량이 어디에 기록됐는지까지 확정하는 것도 피해야 합니다. 공식 게이트웨이 연결 확인 절차

보안과 다음 선택

설정이 예상과 다르면 사용하지 않을 인증을 제공한 정확한 위치부터 찾습니다. 현재 셸인지, 사용자 settings인지, 프로젝트 로컬 설정인지, 편집기 설정인지 확인한 뒤 필요한 항목만 수정하고 같은 실행 환경에서 다시 확인하세요. 관리형 제한은 관리자가 결정해야 합니다.

.credentials.json은 API 연결값을 넣는 settings 파일이 아닙니다. 로그인 자격 증명을 저장하는 방식은 운영체제와 실행 환경에 따라 다릅니다. macOS에서는 Keychain을 사용하고 특정 쓰기 실패 상황에는 파일 저장이 사용될 수 있습니다. 따라서 이 파일이 없다고 인증 실패라고 판단하거나 파일에 API 키를 직접 적어 넣지 마세요. ~/.claude.json도 앱 상태를 저장하는 파일로, API 설정 예제를 넣을 대상이 아닙니다. 자격 증명 저장 방식, 설정 파일 구분

자주 묻는 질문

Claude Code에 apiKeyHelper가 꼭 필요한가요?

아닙니다. 직접 ANTHROPIC_API_KEY를 전달해 사용할 수 있습니다. helper는 별도 명령을 통해 키를 제공해야 하는 환경에서 사용하는 기능입니다. 다른 토큰이나 키도 함께 있으면 실제 인증 선택을 확인해야 합니다. 인증 문서

ANTHROPIC_BASE_URL만 바꾸면 API 사용량으로 결제되나요?

주소 변경만으로 인증과 결제가 전환되지는 않습니다. 게이트웨이 인증 없이 저장된 로그인으로 요청할 수도 있습니다. 게이트웨이 키·토큰을 사용할 때는 연결 규칙과 그 요청을 처리한 계정의 사용량을 함께 확인하세요. 게이트웨이 인증·결제 설명

API 키를 바꿨는데 이전 키가 계속 쓰이는 이유는 무엇인가요?

같은 변수 이름이 settings의 env에도 있는지, Claude Code를 시작한 프로세스에 새 값이 전달됐는지 확인하세요. 파일의 env 값은 같은 이름의 셸 변수보다 우선합니다. 다른 인증이 선택된 상황도 있으므로 /status의 인증 표시와 대화형 키 선택을 함께 봅니다. 환경 변수 적용 규칙

credentials.json이 없으면 새로 만들어야 하나요?

아닙니다. 운영체제별 인증 저장 방식이 다르며 이 파일의 존재가 API 키 설정의 전제는 아닙니다. API 키는 공식 환경 변수·설정 방법으로 전달하고, 저장된 로그인은 지원되는 인증 절차로 관리하세요. 공식 자격 증명 저장 설명