> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Cloud의 Claude 모델(Anthropic 관리형)과 함께 Claude Code 사용하기

> Google Cloud 자격 증명, IAM, Marketplace 청구를 사용하여 Anthropic이 Google Cloud 프로젝트를 통해 운영하는 Claude API를 사용하도록 Claude Code를 구성합니다.

Google Cloud의 Claude 모델(Anthropic 관리형)은 Anthropic이 운영하고 사용자의 Google Cloud 프로젝트를 통해 접근하는 Claude API입니다. Claude Code에서 이를 사용하려면 Google Cloud에 로그인하고 세 개의 환경 변수를 설정합니다.

> [!NOTE]
>
> Google Cloud는 Google이 관리하는 Google Cloud의 Agent Platform(이전 명칭 Vertex AI)을 통해서도 Claude를 제공합니다. Agent Platform을 사용하는 경우 대신 [Google Cloud의 Agent Platform에서 Claude Code 사용하기](https://code.claude.com/docs/ko/google-vertex-ai.md)를 따르십시오. 어떤 것을 사용하고 있는지 확인하려면 [어떤 서비스를 사용하고 있습니까?](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/overview#which-offering-are-you-using)를 참조하십시오.

시작하기 전에 Claude Code v2.1.307 이상을 [설치](https://code.claude.com/docs/ko/setup.md#install-claude-code)하십시오. 버전을 확인하려면 셸에서 `claude --version`을 실행합니다. 업데이트하려면 `claude update`를 실행합니다.

## 사전 요구 사항

* [계정 설정](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#set-up-your-account)이 완료된 Google Cloud 프로젝트
* Claude Code를 실행하는 각 Google 계정 또는 서비스 계정에 대해 해당 프로젝트의 `roles/claude.user` [IAM 역할](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#iam-roles)
* 프로젝트 ID와 `wrkspc_`로 시작하는 [워크스페이스 ID](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#find-your-workspace-id)
* 서비스 계정 키 파일 대신 Google 계정으로 로그인하는 경우 [gcloud CLI](https://cloud.google.com/sdk/docs/install)

## Claude Code 설정

**1. Application Default Credentials 생성**

> [tab] Google 계정
>
> 셸에서 다음 명령을 실행하고 `roles/claude.user` 역할이 있는 Google 계정으로 로그인합니다.
>
> ```bash theme={null}
> gcloud auth application-default login
> ```
>
> 이미 `gcloud auth login`을 실행했더라도 이 명령을 실행하십시오.
>
> `GOOGLE_APPLICATION_CREDENTIALS`가 설정되어 있으면 설정을 해제하십시오. 이 변수가 설정되어 있는 동안 Claude Code는 해당 변수가 가리키는 파일을 사용하고 명령이 저장한 자격 증명은 무시합니다.

> [tab] 서비스 계정 키 파일
>
> Claude Code를 실행하는 셸 또는 CI 작업에서 `GOOGLE_APPLICATION_CREDENTIALS`를 [서비스 계정 키 파일](https://docs.cloud.google.com/iam/docs/keys-create-delete)의 경로로 설정합니다. 다른 자격 증명 소스에 대해서는 [인증 방법](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#authentication)을 참조하십시오.

**2. 설정에 변수 추가**

[사용자 설정 파일](https://code.claude.com/docs/ko/settings.md)인 `~/.claude/settings.json`의 `env` 블록에 세 개의 변수를 추가합니다. 파일이 없으면 다음 내용으로 생성합니다.

```json theme={null}
{
  "env": {
    "CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD": "1",
    "ANTHROPIC_GOOGLE_CLOUD_PROJECT": "my-project-id",
    "ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID": "wrkspc_01ABCDEFGHIJKLMN"
  }
}
```

`my-project-id`와 `wrkspc_` 값 대신 사용자 자신의 프로젝트 ID와 [워크스페이스 ID](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#find-your-workspace-id)를 사용하십시오. 대신 단일 셸이나 CI 작업을 구성하려면 해당 환경에서 동일한 세 개의 변수를 설정합니다.

Anthropic 계정에 로그인하거나 로그아웃할 필요는 없습니다.

**3. Claude Code를 시작하고 제공자 확인**

셸에서 `claude`를 실행한 다음 Claude Code 프롬프트에서 `/status`를 실행합니다. `API provider` 줄에 `on Google Cloud`가 포함되고, 그 다음 줄에 `Workspace ID`, `GCP project`, `GCP location`이 표시됩니다. 셸이나 CI 작업에서 동일한 줄을 출력하려면 [`claude auth status --text`](https://code.claude.com/docs/ko/cli-reference)를 실행합니다.

`on Google Cloud`가 표시되면 프롬프트를 보내거나 CI 작업에서 `claude -p "hello"`를 실행합니다. 응답이 오면 자격 증명과 IAM 역할이 제대로 작동하는 것입니다. 표시되지 않거나 Claude Code에 오류가 표시되면 [제공자 설정 문제를 해결](#troubleshooting)하십시오.

### 팀을 위한 Claude Code 설정

[Claude Code 설정](#set-up-claude-code)의 2단계에 있는 `env` 블록을 각 개발자 컴퓨터의 [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md) 파일에 넣습니다. 각 개발자에게 프로젝트의 `roles/claude.user` 역할을 부여하고, 각자 자신의 컴퓨터에서 `gcloud auth application-default login`을 실행하도록 합니다.

## 모델 버전 고정

팀에 배포하는 경우 Claude Code 업데이트로 인해 모든 사람이 한꺼번에 최신 모델로 이동하지 않도록 [모델 ID를 고정](https://code.claude.com/docs/ko/model-config.md#pin-models-for-third-party-deployments)하십시오. [Claude Code 설정](#set-up-claude-code)의 세 변수가 들어 있는 `env` 블록에 다음 변수를 추가합니다.

```json theme={null}
{
  "env": {
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "claude-fable-5-1",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001"
  }
}
```

예시 값 대신 [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview)에서 원하는 Claude API 모델 ID를 사용하십시오.

## 환경 변수

| 변수 | 필수 | 설명 |
| - | - | - |
| `CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD` | 예 | 모델 요청을 Google Cloud의 Claude 모델(Anthropic 관리형)로 보내려면 `1`로 설정합니다 |
| `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID` | 예. 단, `ANTHROPIC_GOOGLE_CLOUD_BASE_URL`을 설정한 경우는 제외 | 워크스페이스 ID |
| `ANTHROPIC_GOOGLE_CLOUD_PROJECT` | 권장 | Google Cloud 프로젝트 ID. 설정하지 않으면 Claude Code는 `GOOGLE_CLOUD_PROJECT`를 사용합니다 |
| `ANTHROPIC_GOOGLE_CLOUD_LOCATION` | 아니요 | 요청 URL의 [위치](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution). 기본값은 `global`입니다 |
| `ANTHROPIC_GOOGLE_CLOUD_BASE_URL` | 아니요 | Claude Code가 프로젝트, 위치, 워크스페이스 ID로 구성하는 기본 URL을 대체합니다. 예를 들어 [LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway)의 주소로 대체할 수 있습니다. Claude Code는 `/v1/messages`와 같은 API 경로를 뒤에 추가합니다 |
| `CLAUDE_CODE_SKIP_ANTHROPIC_GOOGLE_CLOUD_AUTH` | 아니요 | 게이트웨이가 Google 자격 증명을 직접 첨부하는 경우 `1`로 설정하여 Claude Code가 Google 액세스 토큰을 보내지 않도록 합니다 |

## 사용할 수 없는 Claude Code 기능

Claude Models on Google Cloud (Anthropic managed)에서 사용할 수 없는 기능은 다음과 같습니다.

* [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md): `/fast` 또는 `fastMode` 설정으로 켤 수 없습니다
* [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 및 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)
* [claude.ai의 MCP 커넥터](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai)
* [채널](https://code.claude.com/docs/ko/channels.md)
* [`/design-sync` 및 `/import` 명령](https://code.claude.com/docs/ko/commands#all-commands)
* [서버 관리형 설정](https://code.claude.com/docs/ko/server-managed-settings.md). 팀에 설정을 강제하려면 대신 각 컴퓨터에서 [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)을 사용하십시오

사용할 수 없거나 부분적으로 지원되는 다른 기능을 확인하려면 [기능 가용성 요약](https://code.claude.com/docs/ko/feature-availability.md#summary-by-provider)에서 **Google Cloud (Anthropic managed)** 탭을 선택하십시오.

## 문제 해결

Claude Code가 로그인을 요청하거나 `/status`의 `API provider` 줄에 `on Google Cloud`가 포함되어 있지 않은 경우:

* `CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD`가 `1`인지 확인합니다
* `claude --version`이 2.1.307 이상을 출력하는지 확인합니다
* 셸과 [설정 파일](https://code.claude.com/docs/ko/settings.md#find-or-create-your-settings-files)에서 `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_FOUNDRY`, `CLAUDE_CODE_USE_ANTHROPIC_AWS`를 제거합니다

`CLAUDE_CODE_USE_VERTEX`는 설정된 상태로 두어도 됩니다. 변수를 변경한 후에는 Claude Code를 다시 시작하십시오. `/status`에 변경 사항이 표시되지 않으면 [설정한 값이 무시되는 경우](https://code.claude.com/docs/ko/settings.md#a-value-you-set-is-ignored)를 참조하십시오.

### `No workspace ID found`

`ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID`를 [워크스페이스 ID](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#find-your-workspace-id)로 설정한 다음 Claude Code를 다시 시작합니다. 메시지에 언급된 `workspaceId` 생성자 옵션은 무시하십시오. 이 옵션은 자체 코드에서 Anthropic의 SDK를 호출하는 경우를 위한 것입니다.

### `No project was given`

`ANTHROPIC_GOOGLE_CLOUD_PROJECT`를 Google Cloud 프로젝트 ID로 설정한 다음 Claude Code를 다시 시작합니다.

### `Could not load Google Cloud credentials`

[Claude Code 설정](#set-up-claude-code)의 1단계를 반복합니다. 서비스 계정 키 파일을 사용하는 경우 새 키를 사용합니다.

### `Google Cloud credentials expired or invalid`

메시지에서 Google Cloud 자격 증명을 새로 고치라고 안내하면 [Claude Code 설정](#set-up-claude-code)의 1단계를 반복합니다. 서비스 계정 키 파일을 사용하는 경우 새 키를 사용합니다.

### `Google Cloud authentication failed`

[`Google Cloud credentials expired or invalid`](#google-cloud-credentials-expired-or-invalid)의 단계를 따릅니다. 그래도 오류가 해결되지 않으면:

* **프로젝트**: `/status`에서 `GCP project` 줄에 사용자의 프로젝트가 표시되는지 확인합니다. 다른 프로젝트가 표시되거나 해당 줄이 없으면 [`No project was given`](#no-project-was-given)을 따릅니다
* **워크스페이스**: `/status`에서 `Workspace ID` 줄에 사용자의 워크스페이스 ID가 표시되는지 확인합니다. 다른 ID가 표시되면 [`No workspace ID found`](#no-workspace-id-found)를 따릅니다
* **IAM 역할**: Claude Code를 실행하는 Google 계정 또는 서비스 계정이 `GCP project` 줄에 있는 프로젝트에 대해 `roles/claude.user` 또는 `roles/claude.admin`을 보유하고 있는지 확인합니다. 역할을 부여하려면 [서비스의 권한 부여 명령](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#before-making-api-calls)을 사용하거나 프로젝트 관리자에게 부여를 요청합니다
* **서비스**: `GCP project` 줄에 있는 프로젝트에서 `claude.googleapis.com` 서비스가 활성화되어 있는지 확인합니다. 활성화하려면 [서비스의 계정 설정 단계](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#set-up-your-account)를 따르거나 프로젝트 관리자에게 활성화를 요청합니다

## 관련 리소스

* [Google Cloud의 Claude 모델(Anthropic 관리형)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed): 계정 설정, IAM 역할, 청구, 데이터 보존 및 기능 지원
* [엔터프라이즈 배포 개요](https://code.claude.com/docs/ko/third-party-integrations.md): Claude Code를 배포하는 다른 방법과 프록시 및 게이트웨이 설정
* [모델 구성](https://code.claude.com/docs/ko/model-config.md): 모델 별칭, 모델 버전 고정, 사용자가 선택할 수 있는 모델 제한