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

> 직접 API 키를 쓰려면 Claude Code를 실행할 터미널에 ANTHROPIC_API_KEY를 전달하고 대화형 승인 여부를 확인합니다. 설정이 적용되지 않으면 인증 방식, settings.json의 범위, 모델, 실행한 앱을 차례로 확인하세요.

- URL: https://blog.laozhang.ai/ko/posts/claude-code-api-configuration
- Published: 2026-04-21
- Updated: 2026-10-07
- Author: LaoZhang AI Team (https://blog.laozhang.ai/ko/about)
- Topic: Claude Code
- Tags: Claude Code, Claude API, Anthropic, API 설정, 개발 도구

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

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

## 활성 경로부터 정하기

| 사용하려는 방식 | 먼저 준비할 것 | Claude Code에 전달할 설정 |
| --- | --- | --- |
| Anthropic API 키 | 사용할 Console의 발급된 키와 API 사용 권한 | `ANTHROPIC_API_KEY` |
| Claude 구독 로그인 | Claude Code를 사용할 수 있는 계정 | 지원되는 로그인 절차 |
| 키 없는 Console 로그인 | 지원 버전과 Console 계정 | Console OAuth 기반 Anthropic 프로필 |
| 기존 사내·외부 게이트웨이 | 접속 주소, 인증 방식, 지원 모델 ID | `ANTHROPIC_BASE_URL`과 해당 인증 변수 |
| Bedrock·Google Cloud·Foundry | 해당 공급자의 자격 증명과 모델 접근 권한 | 공급자 선택 플래그와 리전·프로젝트·리소스 설정 |

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

### 발급받은 API 키로 실행하기

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

```bash
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에서는 다음처럼 유무만 확인할 수 있습니다.

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

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

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

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

## credentials 우선순위

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

| 인증 후보 | 적용 조건과 확인할 점 |
| --- | --- |
| 클라우드 공급자의 자격 증명 | `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY` 등 해당 공급자가 선택돼 있을 때 적용됩니다. AWS 자격 증명이 있다는 사실만으로 Bedrock이 선택되지는 않습니다. |
| `ANTHROPIC_AUTH_TOKEN` | Bearer 방식 인증입니다. 일반 CLI 인증 선택에서 API 키와 helper보다 앞섭니다. |
| `ANTHROPIC_API_KEY` | `X-Api-Key` 방식입니다. 대화형 사용 승인과 `-p`의 차이가 있습니다. |
| `apiKeyHelper` | 외부 명령으로 키를 공급하는 설정입니다. 직접 API 키를 쓰는 데 필수는 아닙니다. |
| `CLAUDE_CODE_OAUTH_TOKEN`, 프로필, 저장된 로그인 | 프로필 유형, 명시적인 프로필 선택, 현재 로그인에 따라 적용 관계가 달라집니다. |

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

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

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

```bash
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`에 둡니다. 설치 직후 이 파일이 없을 수도 있습니다. 세 파일을 모두 만들어야 하는 것은 아닙니다. [공식 설정 문서](https://code.claude.com/docs/en/settings)

![관리형 설정부터 사용자 설정까지 같은 항목의 기본 적용 순서를 보여 주는 그림](https://blog.laozhang.ai/posts/ko/claude-code-api-configuration/img/settings-scopes.webp)

| 범위 | 파일 또는 입력 | 알맞은 용도 |
| --- | --- | --- |
| 사용자 | `~/.claude/settings.json` | 여러 프로젝트에서 쓸 개인 기본값 |
| 프로젝트 공유 | `.claude/settings.json` | 팀이 함께 사용하는 비밀이 아닌 설정 |
| 프로젝트 로컬 | `.claude/settings.local.json` | 개인에게만 필요한 프로젝트 설정 |
| 실행 인수 | `--model`, `--settings` 등 | 해당 실행에 필요한 변경 |
| 관리형 | 조직이 배포한 설정 | 조직 정책과 강제 설정 |

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

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

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

```json
{
  "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 값이 적용됩니다. 그래서 터미널의 키만 바꿨는데도 이전 설정이 계속 쓰일 수 있습니다. [게이트웨이 연결 문서의 환경 변수 적용 설명](https://code.claude.com/docs/en/llm-gateway-connect)

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

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

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

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

## API 키와 게이트웨이

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

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

```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`는 두 인증 헤더를 모두 보내므로 어떤 방식을 쓸지는 게이트웨이 문서와 맞춰야 합니다. 주소 변경과 함께 저장된 로그인부터 삭제하는 절차는 필수가 아닙니다. [인증 헤더와 연결 설정](https://code.claude.com/docs/en/llm-gateway-connect)

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

연결한 경로에서 `system`, `developer`, `tool` 역할을 거부하는 400이 나온다면 [시스템 지시와 도구 기록을 보존하는 역할 오류 해결 방법](https://blog.laozhang.ai/ko/posts/api-400-role-system-is-not-supported-on-this-model)을 확인하세요.

## 모델과 제공자 경로

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

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

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

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

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

### Bedrock, Google Cloud, Foundry의 최소 설정

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

| 공급자 | Claude Code 연결 항목 | 함께 맞춰야 할 값 |
| --- | --- | --- |
| Amazon Bedrock | `CLAUDE_CODE_USE_BEDROCK=1` | AWS 자격 증명, 호출 리전, 사용 가능한 모델·추론 프로필. 프로필에 리전이 있으면 `AWS_REGION`은 생략할 수 있습니다. SSO 로그인 리전과 모델 호출 리전은 같다고 가정하지 않습니다. |
| Google Cloud Agent Platform(이전 Vertex AI) | `CLAUDE_CODE_USE_VERTEX=1` | `CLOUD_ML_REGION`, `ANTHROPIC_VERTEX_PROJECT_ID`, ADC 등 지원되는 자격 증명. 요청 프로젝트는 자격 증명을 만든 프로젝트가 아닌 이 변수로 정해집니다. |
| Microsoft Foundry | `CLAUDE_CODE_USE_FOUNDRY=1` | `ANTHROPIC_FOUNDRY_RESOURCE` 또는 `ANTHROPIC_FOUNDRY_BASE_URL`, 접근 권한, 실제 모델 배포 이름 |

각 값은 [Bedrock](https://code.claude.com/docs/en/amazon-bedrock), [Google Cloud](https://code.claude.com/docs/en/google-vertex-ai), [Foundry](https://code.claude.com/docs/en/microsoft-foundry)의 현재 설정 문서와 맞추세요. 리전과 모델의 실제 제공 여부는 계정에서 확인해야 합니다. Foundry 인증은 지원 버전에서 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` → `ANTHROPIC_FOUNDRY_API_KEY` → Azure SDK 기본 인증 순으로 선택됩니다. Foundry는 시작 시 모델 확인을 하지 않으므로 첫 요청에서 배포 이름 오류가 드러날 수 있습니다.

Bedrock 경로를 확인했는데 400이 계속 나면 [AWS Bedrock Claude 400의 메시지별 해결](https://blog.laozhang.ai/ko/posts/aws-claude-400-error)로 오류 원문을 구분하세요. 같은 상태 코드라도 요청 형식, 모델, 리전, 권한 중 고칠 곳이 다릅니다.

## 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 키·토큰 변수로 구독 인증을 덮어쓰는 환경이 아닙니다. [앱별 게이트웨이 설정](https://code.claude.com/docs/en/llm-gateway-connect), [인증 적용 범위](https://code.claude.com/docs/en/authentication)

## 검증 루프

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

![설정 로드부터 인증과 모델, 실제 추론·도구·사용량을 따로 확인하는 단계](https://blog.laozhang.ai/posts/ko/claude-code-api-configuration/img/configuration-to-request-proof.webp)

| 단계 | 확인 방법 | 확인되는 범위 |
| --- | --- | --- |
| 설정 | JSON 문법, `/status`에 표시된 설정 파일 | 파일이 파싱·로드되는지에 관한 단서 |
| 인증·공급자 | `/status`, 대화형 키 선택, 실제 실행한 앱 | 이번 세션이 어떤 인증과 공급자를 선택했는지 |
| 모델 | `/model`, 공급자의 지원 ID·배포 이름 | 선택한 이름이 의도한 공급자에 맞는지 |
| 추론 | 짧은 메시지 한 번에 정상 답변이 오는지 | 해당 요청의 실제 모델 호출 |
| 코딩 작업 | 필요한 파일 읽기·도구 사용이 작동하는지 | 추론 이후에 필요한 도구 기능 |
| 비용 | 요청한 Console·게이트웨이·클라우드의 사용량 기록 | 어느 계정에 사용량이 기록됐는지 |

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

## 보안과 다음 선택

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

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

## 자주 묻는 질문

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

아닙니다. 직접 `ANTHROPIC_API_KEY`를 전달해 사용할 수 있습니다. helper는 별도 명령을 통해 키를 제공해야 하는 환경에서 사용하는 기능입니다. 다른 토큰이나 키도 함께 있으면 실제 인증 선택을 확인해야 합니다. [인증 문서](https://code.claude.com/docs/en/authentication)

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

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

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

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

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

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

## 참고 자료

이 글이 링크한 외부 페이지를 본문에 나온 순서대로 정리했습니다. 마지막 업데이트: 2026-10-07.

- [공식 인증 문서](https://code.claude.com/docs/en/authentication) (code.claude.com)
- [공식 설정 문서](https://code.claude.com/docs/en/settings) (code.claude.com)
- [게이트웨이 연결 문서의 환경 변수 적용 설명](https://code.claude.com/docs/en/llm-gateway-connect) (code.claude.com)
- [게이트웨이의 인증과 결제 관계](https://code.claude.com/docs/en/llm-gateway) (code.claude.com)
- [게이트웨이 프로토콜 요구 사항](https://code.claude.com/docs/en/llm-gateway-protocol) (code.claude.com)
- [공식 모델 설정](https://code.claude.com/docs/en/model-config) (code.claude.com)
- [Bedrock](https://code.claude.com/docs/en/amazon-bedrock) (code.claude.com)
- [Google Cloud](https://code.claude.com/docs/en/google-vertex-ai) (code.claude.com)
- [Foundry](https://code.claude.com/docs/en/microsoft-foundry) (code.claude.com)