> ## 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

> 設定 Claude Code 以使用 Anthropic 透過您的 Google Cloud 專案執行的 Claude API，並搭配 Google Cloud 憑證、IAM 與 Marketplace 計費。

Google Cloud 上的 Claude 模型（由 Anthropic 管理）是由 Anthropic 執行、透過您的 Google Cloud 專案存取的 Claude API。若要從 Claude Code 使用它，請登入 Google Cloud 並設定三個環境變數。

> [!NOTE]
>
> Google Cloud 也透過 Google Cloud 的 Agent Platform（前身為 Vertex AI）提供 Claude，該服務由 Google 管理。如果您使用 Agent Platform，請改為依照 [Google Cloud 的 Agent Platform 上的 Claude Code](https://code.claude.com/docs/zh-TW/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](https://code.claude.com/docs/zh-TW/setup.md#install-claude-code) v2.1.307 或更新版本。若要檢查版本，請在 shell 中執行 `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)
* [gcloud CLI](https://cloud.google.com/sdk/docs/install)，如果您是以 Google 帳戶登入，而非使用服務帳戶金鑰檔案

## 設定 Claude Code

**1. 建立應用程式預設憑證**

> [tab] Google 帳戶
>
> 在 shell 中執行此命令，並以具備 `roles/claude.user` 角色的 Google 帳戶登入：
>
> ```bash theme={null}
> gcloud auth application-default login
> ```
>
> 即使您已經執行過 `gcloud auth login`，仍請執行此命令。
>
> 如果已設定 `GOOGLE_APPLICATION_CREDENTIALS`，請取消設定。只要設定了該變數，Claude Code 就會使用其指定的檔案，並忽略此命令儲存的憑證。

> [tab] 服務帳戶金鑰檔案
>
> 在執行 Claude Code 的 shell 或 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/zh-TW/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"
  }
}
```

請以您自己的專案 ID 與[工作區 ID](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#find-your-workspace-id) 取代 `my-project-id` 與 `wrkspc_` 值。若要改為設定單一 shell 或 CI 工作，請在該環境中設定相同的三個變數。

您不需要登入 Anthropic 帳戶，也不需要從中登出。

**3. 啟動 Claude Code 並檢查供應商**

在 shell 中執行 `claude`，然後在 Claude Code 提示字元執行 `/status`。`API provider` 行會包含 `on Google Cloud`，其後的各行會顯示您的 `Workspace ID`、`GCP project` 與 `GCP location`。若要從 shell 或 CI 工作輸出相同的內容，請執行 [`claude auth status --text`](https://code.claude.com/docs/zh-TW/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/zh-TW/managed-settings.md)檔案中。在專案上授予每位開發人員 `roles/claude.user` 角色，並請每位開發人員在自己的電腦上執行 `gcloud auth application-default login`。

## 固定模型版本

如果您部署給團隊使用，請[固定模型 ID](https://code.claude.com/docs/zh-TW/model-config.md#pin-models-for-third-party-deployments)，以免 Claude Code 更新時讓所有人同時改用較新的模型。請將這些變數加入包含[設定 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` | 是 | 設為 `1` 以將模型請求傳送至 Google Cloud 上的 Claude 模型（由 Anthropic 管理） |
| `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/zh-TW/llm-gateway)的位址。Claude Code 會附加 API 路徑，例如 `/v1/messages` |
| `CLAUDE_CODE_SKIP_ANTHROPIC_GOOGLE_CLOUD_AUTH` | 否 | 當閘道自行附加 Google 憑證時設為 `1`，讓 Claude Code 不傳送 Google 存取 token |

## 無法使用的 Claude Code 功能

使用 Claude Models on Google Cloud (Anthropic managed) 時，無法使用的功能包括：

* [快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)：您無法透過 `/fast` 或 `fastMode` 設定將其開啟
* [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 與[雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)
* [來自 claude.ai 的 MCP 連接器](https://code.claude.com/docs/zh-TW/mcp.md#use-mcp-servers-from-claude-ai)
* [頻道](https://code.claude.com/docs/zh-TW/channels.md)
* [`/design-sync` 與 `/import` 命令](https://code.claude.com/docs/zh-TW/commands#all-commands)
* [伺服器管理設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)。若要為您的團隊強制套用設定，請改為在每台電腦上使用[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)

若要查看其他無法使用或僅部分支援的功能，請在[功能可用性摘要](https://code.claude.com/docs/zh-TW/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 或更新版本
* 從您的 shell 與[設定檔](https://code.claude.com/docs/zh-TW/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/zh-TW/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/zh-TW/third-party-integrations.md)：部署 Claude Code 的其他方式，以及代理伺服器與閘道設定
* [模型設定](https://code.claude.com/docs/zh-TW/model-config.md)：模型別名、固定模型版本，以及限制使用者可選擇的模型