---
title: Claude Models on Google Cloud (Anthropic managed)
url: https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed
description: Claude Models on Google Cloud (Anthropic managed) 是由 Anthropic 營運、透過您的 Google Cloud 專案存取的 Claude API。
---
Google Cloud 負責處理 Claude Models on Google Cloud (Anthropic managed) 的存取與計費。若要比較兩種 Google Cloud 方案，或確認您使用的是哪一種，請參閱 [Claude Models on Google Cloud](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/overview)。
## 設定您的帳戶
若要為 Claude Models on Google Cloud (Anthropic managed) 設定您的帳戶，您需要具備以下條件：
* 在您的計費帳戶上於 Google Cloud Marketplace 進行購買的權限
* 在專案上啟用服務的權限
* 一個[可讓您開啟 Claude Console 的 IAM 角色](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#using-the-claude-console)，步驟 4 需要用到
這些步驟會為您的 Google Cloud 專案建立一個新的 Anthropic 組織。它與您公司既有的任何 Anthropic 組織是分開的，包括 Claude Enterprise 組織。若要從既有組織遷移，請參閱[從既有的 Anthropic 組織遷移](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#moving-from-an-existing-anthropic-organization)。
如果您已有折扣，請在開始這些步驟之前聯絡您的 Anthropic 或 Google Cloud 客戶代表。折扣無法套用於過去的使用量。
1. 開啟 [Google Cloud Marketplace](https://console.cloud.google.com/marketplace)，找到 **Claude Models on Google Cloud (Anthropic managed)** 商品頁面。
2. 選擇 **Subscribe** 並完成購買流程。
3. 返回商品頁面並選擇 **Manage on Console**。這會在 Google Cloud 主控台中開啟 Claude 頁面。
若之後要返回 Claude 頁面，請在 Google Cloud 主控台中選取您的專案。然後前往 **Agent Platform > Models > Claude Platform** 並選擇 **Anthropic managed**。
在每個呼叫 Claude Models on Google Cloud (Anthropic managed) 的專案上啟用兩項服務：
* `claude.googleapis.com` 提供 Claude Models on Google Cloud (Anthropic managed) 的 API。此服務也定義了 IAM 權限。沒有它，呼叫將會失敗。
* `anthropic-managed-claude.cloudpartnerservices.goog` 是將專案使用量歸屬到您訂閱的 Marketplace 服務。
```bash CLI
gcloud services enable claude.googleapis.com \
anthropic-managed-claude.cloudpartnerservices.goog \
--project=my-project-id
```
將 `my-project-id` 替換為您的專案 ID。
您也可以從 Claude 頁面或 **APIs & Services** 啟用這兩項服務。每個專案只需啟用一次。若要確認兩項服務都已啟用，請執行 `gcloud services list --enabled --project=my-project-id` 並尋找這兩個名稱。
1. 在 Claude 頁面上，選擇 **Activate**。
2. 在 Anthropic 設定流程中，輸入聯絡電子郵件地址。
3. 開啟寄送到該地址的設定連結。
4. 填寫組織名稱、實體類型、國家/地區及預期用途。
5. 接受 Anthropic 的商業服務條款與使用政策。
聯絡地址僅用於設定與服務通知。關於設定完成後使用者如何開啟 Claude Console，請參閱[使用 Claude Console](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#using-the-claude-console)。
當您的 Anthropic 組織啟用後，Claude 頁面上的按鈕會變為 **Open Claude Console**。選擇它。Google Cloud 會檢查您的 IAM 存取權限，然後將您的瀏覽器重新導向至 `platform.claude.com`。您會登入新的組織。
在 Claude Console 中，[找到您的工作區 ID](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#find-your-workspace-id) 並複製它。每個呼叫 Claude Models on Google Cloud (Anthropic managed) 的人都需要它。請將它轉交給您的開發人員。
若要新增另一個專案，請在該專案中從步驟 2 開始重複這些步驟。
### 帳戶設定疑難排解
如果您在設定 Claude Models on Google Cloud (Anthropic managed) 時遇到以下任一問題，請套用對應的修正方式：
* **`gcloud services enable` 找不到 `anthropic-managed-claude.cloudpartnerservices.goog`：** 請以完成 Marketplace 購買的帳戶執行該指令，或聯絡您的 Anthropic 客戶代表。
* **第一次 API 呼叫時出現權限錯誤：** 請確認您呼叫的專案已啟用 `claude.googleapis.com`。確認呼叫者在該專案上具有 `roles/claude.user` 或 `roles/claude.admin`。關於各角色允許的操作，請參閱 [IAM 角色](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#iam-roles)。新的授權或新啟用的服務可能需要一點時間才會生效。
* **依照設定連結操作後顯示「Signed in as a different account」：** 選擇 **Log out and continue**。然後使用您在步驟 3 中輸入的電子郵件地址。
* **按鈕顯示「Finish Setup」而非「Open Claude Console」：** 您的 Anthropic 組織已存在，但其設定尚未完成。管理員必須完成組織詳細資料表單。
* **第一次 API 呼叫後，Usage 頁面沒有顯示資料：** 使用量資料可能需要幾分鐘才會出現在 Claude Console 中。
## 管理存取權限
### IAM 角色
Claude Models on Google Cloud (Anthropic managed) 有三個預先定義的 IAM 角色。請在專案上授予角色。
| 角色 | 顯示名稱 | 允許的操作 |
| --------------------- | ------------- | --------------------------------------------------------------------------------------------------------- |
| `roles/claude.viewer` | Claude Viewer | 工作區資源上的所有 `get` 與 `list` 權限
此角色為唯讀。 |
| `roles/claude.user` | Claude User | `roles/claude.viewer` 允許的所有操作，加上建立與變更工作區資源
這包括傳送訊息與計算 token，也包括管理批次、檔案、技能及 Claude Managed Agents 資源。 |
| `roles/claude.admin` | Claude Admin | `roles/claude.user` 允許的所有操作，加上在您的 Anthropic 組織上檢查的權限
組織層級的路由作用於整個 Anthropic 組織，而非單一工作區。 |
例如，以下指令可讓服務帳戶呼叫 Claude Models on Google Cloud (Anthropic managed)：
```bash CLI
gcloud projects add-iam-policy-binding my-project-id \
--member="serviceAccount:my-app@my-project-id.iam.gserviceaccount.com" \
--role="roles/claude.user"
```
關於權限、預先定義的角色及稽核記錄類型，請參閱 [Claude Models on Google Cloud (Anthropic managed) 的 IAM 權限](https://platform.claude.com/docs/zh-TW/api/claude-models-on-google-cloud-anthropic-managed-iam-permissions)。
啟用 `claude.googleapis.com` 會為專案建立一個服務代理。請勿移除其角色授權。移除它們會導致 Claude Models on Google Cloud (Anthropic managed) 在該專案中無法運作。
### 使用 Claude Console
使用 Claude Models on Google Cloud (Anthropic managed) 時，您無法使用電子郵件地址登入您的 Anthropic 組織。請改為在 Google Cloud 主控台的 [Claude 頁面](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#set-up-your-account)上選擇 **Open Claude Console**。Google Cloud IAM 控制誰可以開啟 Claude Console。在三個預先定義的 [IAM 角色](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#iam-roles)中，只有專案上的 `roles/claude.admin` 可讓您開啟 Claude Console。
### 工作區
在 Claude Models on Google Cloud (Anthropic managed) 中，設定流程會建立您的 Anthropic 組織，並附帶一個工作區，即 Default Workspace。若要建立更多工作區，請[開啟 Claude Console](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#using-the-claude-console) 並前往 **Settings > Workspaces**。在同一頁面上，您可以重新命名或封存 Default Workspace 以外的任何工作區。每個工作區都有自己的[工作區 ID](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#find-your-workspace-id)。檔案、技能、批次、Claude Managed Agents 工作階段及其他工作區資源，屬於您[為請求設定](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution)的 ID 所對應的工作區。
您是在專案上授予 [IAM 角色](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#iam-roles)，因此角色會套用到該專案中的每個工作區。當團隊需要分開的存取權限時，請為每個團隊提供各自的 Google Cloud 專案。每個專案都有自己的 Anthropic 組織，因此請在每個專案中從步驟 2 開始重複[設定步驟](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#set-up-your-account)。
## 進行 API 呼叫之前
若要呼叫 Claude Models on Google Cloud (Anthropic managed)，您需要具備以下條件：
1. 一個具有有效訂閱、且 Anthropic 組織已完成設定的 Google Cloud 專案。請參閱[設定您的帳戶](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#set-up-your-account)。
2. 已安裝 [gcloud CLI](https://cloud.google.com/sdk/docs/install)，用於本機開發。
3. 在專案上授予進行呼叫之身分的 `roles/claude.user` 角色。
4. 該身分的 Application Default Credentials。請參閱[驗證](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#authentication)。
5. 您的專案 ID 與[工作區 ID](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#find-your-workspace-id)。
若要為本機開發將角色授予您自己的帳戶，請執行以下指令。您需要具備變更專案 IAM 政策的權限。
```bash CLI
gcloud projects add-iam-policy-binding my-project-id \
--member="user:you@example.com" \
--role="roles/claude.user"
```
將 `my-project-id` 替換為您的專案 ID。將 `you@example.com` 替換為您 Google 帳戶的電子郵件地址。若要查看 gcloud 正在使用的專案，請執行 `gcloud config get-value project`。關於服務帳戶及其他角色，請參閱 [IAM 角色](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#iam-roles)。
### 找到您的工作區 ID
若要找到 Claude Models on Google Cloud (Anthropic managed) 的工作區 ID，請[開啟 Claude Console](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#using-the-claude-console) 並前往 **Settings > Workspaces**。ID 以 `wrkspc_` 開頭。如果您無法開啟 Claude Console，請向能夠開啟的人索取 ID。
將專案與工作區設定為環境變數，讓 SDK 用戶端與 [`ant` CLI](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/quickstart) 能夠讀取：
```bash CLI
export ANTHROPIC_GOOGLE_CLOUD_PROJECT="my-project-id"
export ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID="wrkspc_01AbCdEf23GhIj"
```
### 安裝 SDK
Claude Models on Google Cloud (Anthropic managed) 的 [SDK 用戶端](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/overview)是 `AnthropicGoogleCloud` (csharp: `AnthropicGoogleCloudClient`; go: `googlecloud.NewClient`; java: `GoogleCloudBackend`; php: `Anthropic\GoogleCloud\Client`; ruby: `Anthropic::GoogleCloudClient`)。用戶端會解析您的 Google 憑證，並根據您的專案、位置及工作區 ID 建構基礎 URL。
Claude Models on Google Cloud (Anthropic managed) 的 SDK 用戶端目前為 beta 版。
安裝提供該用戶端的套件：
```bash
pip install -U "anthropic[google_cloud]"
```
```bash
npm install @anthropic-ai/google-cloud-sdk
```
```bash
dotnet add package Anthropic.GoogleCloud
```
```bash
go get github.com/anthropics/anthropic-sdk-go
```
```kotlin Gradle
implementation("com.anthropic:anthropic-java:3.1.0")
implementation("com.anthropic:anthropic-java-google-cloud:3.1.0")
```
```xml Maven
com.anthropic
anthropic-java
3.1.0
com.anthropic
anthropic-java-google-cloud
3.1.0
```
```bash
composer require anthropic-ai/sdk google/auth
```
```bash
gem install anthropic googleauth
```
若要改用 `ant` CLI，請[安裝或更新](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/quickstart#installation)至最新版本。不支援 Claude Models on Google Cloud (Anthropic managed) 的版本會忽略 `ANTHROPIC_GOOGLE_CLOUD_*` 變數，然後執行以下其中一項：
* 使用您已設定的任何其他憑證將請求傳送至 Claude API
* 因驗證錯誤而失敗
## 發送請求
Claude Models on Google Cloud (Anthropic managed) 在一個包含您的專案、位置及工作區名稱的基礎 URL 下提供 Claude API 端點：
```text wrap
https://claude.googleapis.com/v1/projects/{project}/locations/global/workspaces/{workspace}/invoke
```
[組織層級的路由](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#iam-roles)（其路徑以 `/v1/organizations/` 開頭）使用不含工作區的基礎 URL：
```text wrap
https://claude.googleapis.com/v1/projects/{project}/locations/global/claudeOrganization/invoke
```
如果您沒有[設定基礎 URL](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution)，SDK 用戶端會針對每個請求在這兩者之間選擇。
將 Claude API 路徑附加到基礎 URL 之後。例如，[Messages API](https://platform.claude.com/docs/zh-TW/api/messages/create) 位於 `.../invoke/v1/messages`。與 Claude API 請求相比，有三處不同：
* **基礎 URL：** 使用前面所示的專案範圍 URL，取代 `https://api.anthropic.com`。
* **驗證：** 使用帶有 Google 存取權杖的 `Authorization: Bearer` 標頭。請勿傳送 `x-api-key` 標頭。
* **工作區：** 工作區 ID 是 URL 的一部分。請勿傳送 `anthropic-workspace-id` 標頭。
其他一切都與 Claude API 相同，包括以下項目：
* `anthropic-version` 與 `anthropic-beta` 標頭
* 請求主體
* 串流
* 回應
本文件其他地方的程式碼範例會建立 Claude API 用戶端並讀取 API 金鑰。若要在 Claude Models on Google Cloud (Anthropic managed) 上執行這些範例，請將其匯入與用戶端建構函式替換為以下範例中的內容。對於 cURL 範例，請套用前面列出的三處差異。
執行這些範例之前，請先完成[進行 API 呼叫之前](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#before-making-api-calls)中的步驟。
```bash cURL
curl "https://claude.googleapis.com/v1/projects/$ANTHROPIC_GOOGLE_CLOUD_PROJECT/locations/global/workspaces/$ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID/invoke/v1/messages" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "content-type: application/json" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, Claude"}
]
}'
```
```bash CLI
ant messages create \
--model claude-opus-5-5 \
--max-tokens 1024 \
--message '{role: user, content: "Hello, Claude"}'
```
```python Python
from anthropic import AnthropicGoogleCloud
client = AnthropicGoogleCloud()
message = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)
```
```typescript TypeScript
import { AnthropicGoogleCloud } from "@anthropic-ai/google-cloud-sdk";
const client = new AnthropicGoogleCloud();
const message = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude" }]
});
console.log(message);
```
```csharp C#
using Anthropic.GoogleCloud;
using Anthropic.Models.Messages;
var client = new AnthropicGoogleCloudClient();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = [new UserMessageParam { Content = "Hello, Claude" }]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
import (
"context"
"fmt"
"github.com/anthropics/anthropic-sdk-go"
"github.com/anthropics/anthropic-sdk-go/googlecloud"
)
func main() {
client, err := googlecloud.NewClient(context.Background(), googlecloud.ClientConfig{})
if err != nil {
panic(err)
}
message, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")),
},
})
if err != nil {
panic(err)
}
fmt.Println(message)
}
```
```java Java
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.googlecloud.backends.GoogleCloudBackend;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
void main() {
AnthropicClient client = AnthropicOkHttpClient.builder()
.backend(GoogleCloudBackend.fromEnv())
.build();
Message message = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.addUserMessage("Hello, Claude")
.build()
);
IO.println(message);
}
```
```php PHP
use Anthropic\GoogleCloud\Client;
use Anthropic\Messages\Model;
$client = new Client();
$message = $client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'Hello, Claude']],
);
echo $message;
```
```ruby Ruby
require "anthropic"
client = Anthropic::GoogleCloudClient.new
message = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude" }]
)
puts message
```
cURL 範例會向 gcloud 要求一個 Application Default Credentials 權杖。存取權杖的有效期很短。請為每個工作階段產生一個，而不要儲存它。
### API 模型 ID
Claude Models on Google Cloud (Anthropic managed) 使用與 Claude API 相同的模型 ID，例如 `claude-opus-5-5`。關於模型及其 ID，請參閱[模型概覽](https://platform.claude.com/docs/zh-TW/models/overview)。
在 Claude Models on Google Cloud (Anthropic managed) 中，請求您的 Anthropic 組織無法使用的模型會傳回錯誤。錯誤訊息為 `Model {model} is not available for this organization's inference configuration.`
## 專案、位置與工作區解析
Claude Models on Google Cloud (Anthropic managed) 的用戶端接受下表中的設定。建立用戶端時傳入的值優先於環境變數。若要明確設定專案與工作區 ID，請傳入 `project` (go: `Project`; java: `.project()`; csharp: `GoogleCloudClientOptions.Project`; cli: `--google-cloud-project`) 與 `workspace_id` (typescript, php: `workspaceId`; go: `WorkspaceID`; java: `.workspaceId()`; csharp: `GoogleCloudClientOptions.WorkspaceId`; cli: `--google-cloud-workspace-id`)。
| 設定 | 環境變數 | 若未設定 |
| ------ | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 專案 ID | `ANTHROPIC_GOOGLE_CLOUD_PROJECT`，其次為 `GOOGLE_CLOUD_PROJECT` | Application Default Credentials 回報的專案（當憑證類型帶有專案時） |
| 工作區 ID | `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID` | 除非您設定了基礎 URL，否則用戶端會引發錯誤。[組織層級的路由](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#iam-roles)不需要工作區 ID。 |
| 位置 | `ANTHROPIC_GOOGLE_CLOUD_LOCATION` | `global` |
| 基礎 URL | `ANTHROPIC_GOOGLE_CLOUD_BASE_URL` | 根據專案、位置及工作區 ID 推導 |
請將位置保留為 `global`。位置與推論執行的地點是分開的，因此若要僅在美國進行推論，請在每個請求上設定 `inference_geo: "us"`，如[資料駐留](https://platform.claude.com/docs/zh-TW/manage-claude/data-residency#inference-geo)中所述。
`ant` CLI 以旗標形式接受相同的設定：
* **專案 ID：** `--google-cloud-project`
* **工作區 ID：** `--google-cloud-workspace-id`
* **位置：** `--google-cloud-location`
* **基礎 URL：** `--google-cloud-base-url`
當設定了專案、工作區 ID 或位置時，CLI 會使用 Claude Models on Google Cloud (Anthropic managed)。僅設定 `GOOGLE_CLOUD_PROJECT`、基礎 URL 或兩者並不足夠。
## 驗證
每個傳送至 Claude Models on Google Cloud (Anthropic managed) 的請求都會在 `Authorization: Bearer` 標頭中攜帶 Google OAuth 2.0 存取權杖。該權杖具有 `https://www.googleapis.com/auth/cloud-platform` 範圍。
Google Cloud 負責處理存取。其位於 `claude.googleapis.com` 的閘道會對每個請求執行以下操作：
1. 檢查您的 Google Cloud 憑證。
2. 檢查呼叫者是否具有請求所需的 IAM 權限。如果沒有，Google Cloud 會傳回 HTTP 403 錯誤。
3. 將請求轉送給 Anthropic。Anthropic 會驗證該請求。
若要授予權限，請參閱 [IAM 角色](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#iam-roles)。
SDK 用戶端從 [Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials)（ADC）取得權杖。ADC 支援的任何憑證來源皆可使用：
* **本機開發：** 執行 `gcloud auth application-default login`。
* **在 Google Cloud 上：** 用戶端會自動使用附加到工作負載的服務帳戶，例如在 Compute Engine、GKE 或 Cloud Run 上。
* **服務帳戶金鑰檔案：** 將 `GOOGLE_APPLICATION_CREDENTIALS` 設定為其路徑。
* **Workload Identity Federation 與服務帳戶模擬：** 依照您對任何 Google Cloud API 的方式進行設定。
確認 ADC 正常運作：
```bash CLI
gcloud auth application-default print-access-token
```
Claude Models on Google Cloud (Anthropic managed) 不使用 API 金鑰。在 Claude Console 中，您無法為設定流程建立的 Anthropic 組織建立 API 金鑰。Claude Models on Google Cloud (Anthropic managed) 的 SDK 用戶端會忽略以下環境變數：
* `ANTHROPIC_API_KEY`
* `ANTHROPIC_AUTH_TOKEN`
* `ANTHROPIC_BASE_URL`
### 憑證優先順序
Claude Models on Google Cloud (Anthropic managed) 的 SDK 用戶端會依以下順序檢查憑證，並使用找到的第一個：
1. 建立用戶端時以 `token_provider` (typescript: `bearerTokenProvider`; csharp: `GoogleCloudClientOptions.TokenProvider`; go: `TokenSource`; java: `.bearerTokenSupplier()`; php: `tokenProvider`) 傳入的權杖提供者。它是一個傳回存取權杖的函式或權杖來源。用戶端會在每個請求時向它要求權杖。權杖的快取與更新由您負責。
2. 建立用戶端時以 `credentials` (typescript: `googleAuth`; csharp: `GoogleCloudClientOptions.GoogleCredential`; java: `.googleCredentials()`; php: `googleCredentials`; ruby: `google_credentials`) 傳入的 Google 憑證物件。Go SDK 沒有此選項。
3. Application Default Credentials。
Go 與 Java 與其他 SDK 有所不同：
* **Go：** 對於選項 1，用戶端接受 `oauth2.TokenSource`。它會快取權杖直到權杖過期。
* **Java：** 使用 `GoogleCloudBackend.fromEnv()` 讀取 Application Default Credentials 以及[專案、位置與工作區解析](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution)中的環境變數。
用戶端沒有專屬於憑證的環境變數。請改用 ADC 的 `GOOGLE_APPLICATION_CREDENTIALS`。
如果您的請求經過會為您附加權杖的代理伺服器，請設定 `skip_auth` (typescript, php: `skipAuth`; go: `SkipAuth`; java: `.skipAuth()`; csharp: `GoogleCloudClientOptions.SkipAuth`)。用戶端便不會傳送 `Authorization` 標頭。此設定無法與前述的憑證選項合併使用。
當 `ant` CLI 使用 Claude Models on Google Cloud (Anthropic managed) 時，它一律從 Application Default Credentials 取得權杖。它不接受權杖提供者、憑證物件或略過驗證的設定。
在搭配 Claude Models on Google Cloud (Anthropic managed) 使用 `ant` 之前，請確認以下項目皆未設定：
* API 金鑰
* 驗證權杖
* `--profile` 或 `ANTHROPIC_PROFILE`，如果它指定了 CLI 可用來驗證的[設定檔](https://platform.claude.com/docs/zh-TW/manage-claude/wif-reference#profile-configuration-file)
* 任何 Anthropic 的聯合變數：
* `ANTHROPIC_FEDERATION_RULE_ID`
* `ANTHROPIC_ORGANIZATION_ID`
* `ANTHROPIC_SERVICE_ACCOUNT_ID`
* `ANTHROPIC_IDENTITY_TOKEN`
* `ANTHROPIC_IDENTITY_TOKEN_FILE`
如果設定了其中任何一項，CLI 會使用該憑證，而非[找到您的工作區 ID](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#find-your-workspace-id) 中的 Google Cloud 設定。如果只設定了部分聯合變數，CLI 會因錯誤而停止。當設定了多個憑證時，CLI 會印出一則說明，指出它使用的是哪一個。
另外，請勿設定 `ANTHROPIC_WORKSPACE_ID` 與 `--workspace-id` 旗標。CLI 仍會將該值作為 `anthropic-workspace-id` 標頭傳送。傳送至 Claude Models on Google Cloud (Anthropic managed) 的請求不得攜帶該標頭。請改用 `--google-cloud-workspace-id` 或 `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID` 設定工作區。
與 SDK 用戶端相同，CLI 不會將 Claude Models on Google Cloud (Anthropic managed) 的請求傳送至 `--base-url` 或 `ANTHROPIC_BASE_URL`。
## 功能支援
本節列出可在 Claude Models on Google Cloud (Anthropic managed) 上運作的功能，以及不受支援的功能。本節並未列出所有 Claude API 功能，也不說明未列出的功能是否可運作。
以下功能在 Claude Models on Google Cloud (Anthropic managed) 上的運作方式與在 Claude API 上相同：
* **「Fast mode」（快速模式）：** 適用於 Claude Opus 5.5 的[快速模式](https://platform.claude.com/docs/zh-TW/build-with-claude/fast-mode)。
- **Beta 功能：** 如果某項 beta 功能在 Claude API 上僅限特定組織使用，則設定流程建立的 Anthropic 組織也需要相同的存取權限。
- **工具：** [工具使用](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/overview)，包括：
* 網頁搜尋
* 網頁擷取
* 程式碼執行
* 記憶工具
* 顧問工具
* MCP 連接器
- **技能與檔案：** [Agent Skills](https://platform.claude.com/docs/zh-TW/agents-and-tools/agent-skills/overview) 與 [Files API](https://platform.claude.com/docs/zh-TW/build-with-claude/files)。
- **模型功能：**
* [提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching)
* [擴展思考](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking)
* [伺服器端備援](https://platform.claude.com/docs/zh-TW/build-with-claude/refusals-and-fallback#server-side-fallback)
* [串流](https://platform.claude.com/docs/zh-TW/build-with-claude/streaming)
* [結構化輸出](https://platform.claude.com/docs/zh-TW/build-with-claude/structured-outputs)
* [Token 計數](https://platform.claude.com/docs/zh-TW/build-with-claude/token-counting)
- **批次與模型：** [Message Batches API](https://platform.claude.com/docs/zh-TW/build-with-claude/batch-processing) 與 Models API。
若要為設定流程建立的 Anthropic 組織開啟或關閉 [Compliance API](https://platform.claude.com/docs/zh-TW/manage-claude/compliance-api)，請[開啟 Claude Console](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#using-the-claude-console)，前往 **Settings > Compliance**，並使用 **Compliance API** 切換開關。
「Customer-managed encryption keys」（客戶管理的加密金鑰），即 CMEK，可搭配 Google Cloud KMS 金鑰使用。若要為設定流程建立的 Anthropic 組織啟用 CMEK，請參閱[客戶管理的加密金鑰](https://platform.claude.com/docs/zh-TW/manage-claude/cmek)。若要設定金鑰，請依照[為 CMEK 設定 Google Cloud KMS](https://platform.claude.com/docs/zh-TW/manage-claude/cmek-google-cloud-kms) 操作。然後在 [Claude Console](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#using-the-claude-console) 中註冊、驗證並附加金鑰，如設定頁面的 **Claude Console** 分頁所述。
### Claude Managed Agents
[Claude Managed Agents](https://platform.claude.com/docs/zh-TW/managed-agents/overview) 可透過 Claude Models on Google Cloud (Anthropic managed) 使用，包括以下項目：
* [代理](https://platform.claude.com/docs/zh-TW/managed-agents/agent-setup)
* [環境](https://platform.claude.com/docs/zh-TW/managed-agents/environments)
* [工作階段](https://platform.claude.com/docs/zh-TW/managed-agents/sessions)
* [憑證保管庫](https://platform.claude.com/docs/zh-TW/managed-agents/vaults)
* [記憶儲存區](https://platform.claude.com/docs/zh-TW/managed-agents/memory)
* [排程部署](https://platform.claude.com/docs/zh-TW/managed-agents/scheduled-deployments)
* [自行託管的沙箱](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes)
存取權限是在建立工作階段或部署時檢查，而非在其執行期間：
* **執行中的工作階段會持續執行。** 如果您撤銷建立工作階段之身分的 Google Cloud 存取權限，該工作階段不會停止。若要停止它，請單獨傳送一個 [`user.interrupt` 事件](https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming#integrating-events)給它。工作階段變為 `idle` 後，您可以封存或刪除它。
* **排程部署會持續執行。** 部署不會在每次排程執行時重新檢查其建立者的存取權限。若要停止它，請暫停、更新或封存它。
當您移除使用者或輪替服務帳戶時，請檢查該身分所建立的工作階段與部署。
### 不支援的功能
以下項目在 Claude Models on Google Cloud (Anthropic managed) 上不受支援：
* **API 金鑰：** 僅能透過 Google Cloud 憑證進行驗證。
* **MCP 通道：** [MCP 通道](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/overview)在 Claude Models on Google Cloud (Anthropic managed) 上無法使用。
* **[自行託管環境上的記憶體儲存區](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-memory)：** 自行託管環境上的工作階段不支援記憶體儲存區。
* **預先建置的自行託管沙箱 worker：** `ant` CLI 以及 Python、TypeScript 和 Go SDK 中的[自行託管 worker](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-workers) 不支援 Claude Models on Google Cloud (Anthropic managed)。請改為實作您自己的 worker，直接呼叫 [Environments Work 端點](https://platform.claude.com/docs/zh-TW/api/beta/environments/work)。關於您的 worker 所需的角色和權限，請參閱[環境的 IAM 權限](https://platform.claude.com/docs/zh-TW/api/claude-models-on-google-cloud-anthropic-managed-iam-permissions#environments)。
### 上下文視窗
Claude Models on Google Cloud (Anthropic managed) 上的「context window」（上下文視窗）大小與 Claude API 相同。關於各模型的限制，請參閱[上下文視窗](https://platform.claude.com/docs/zh-TW/build-with-claude/context-windows)。
## 計費、速率限制與記錄
### 速率限制
Anthropic 管理 Claude Models on Google Cloud (Anthropic managed) 的「rate limit」（速率限制）。若要申請更高的限制，請聯絡您的 Anthropic 客戶代表或[聯絡銷售團隊](https://claude.com/contact-sales)。關於速率限制的衡量與回報方式，請參閱[速率限制](https://platform.claude.com/docs/zh-TW/api/rate-limits)。
### 計費
Claude Models on Google Cloud (Anthropic managed) 透過 Google Cloud Marketplace 計費。Anthropic 會計量您的使用量，並以 Claude Consumption Units 向 Google Cloud 回報。費用會顯示在您的 Google Cloud 帳單上。Anthropic 不會另外寄送發票。
在 [Claude Console](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#using-the-claude-console) 的 **Usage** 與 **Cost** 頁面上檢視使用量與費用資料。
如果您有 Google Cloud 支出承諾，使用量會如同其他 Marketplace 購買一樣計入該承諾。
### 資料保留
Anthropic 是 Claude Models on Google Cloud (Anthropic managed) 的資料處理者。部分支援服務（例如 Anthropic 的信任與安全系統）會在 Google Cloud 之外處理資料。
Claude Models on Google Cloud (Anthropic managed) 遵循與 Claude API 相同的資料保留政策。請參閱 [API 與資料保留](https://platform.claude.com/docs/zh-TW/manage-claude/api-and-data-retention)。「Zero Data Retention」（零資料保留），即 ZDR，可依要求提供。請聯絡您的 Anthropic 客戶代表。
其他 Anthropic 組織上的 ZDR 安排不會延續到您用於 Claude Models on Google Cloud (Anthropic managed) 的組織。
### 監控與記錄
[Cloud Audit Logs](https://cloud.google.com/logging/docs/audit) 會記錄您專案中 Claude Models on Google Cloud (Anthropic managed) 的 API 活動。這些項目會顯示在 `claude.googleapis.com` 服務下。每個 API 路由屬於以下兩種記錄類型之一：
* **Data Access 記錄：** 涵蓋大多數路由，包括訊息、批次、檔案、技能、模型及大多數 Claude Managed Agents 資源。預設為關閉。
* **Admin Activity 記錄：** 涵蓋其他路由，包括加密金鑰路由及大多數憑證保管庫路由。例外是 `vaults.verify` 的路由，它屬於 Data Access。Admin Activity 記錄一律開啟。
若要保留請求記錄，請在專案的稽核記錄設定中為 `claude.googleapis.com` 開啟 Data Access 記錄。
關於各路由的稽核記錄類型，請參閱 [Claude Models on Google Cloud (Anthropic managed) 的 IAM 權限](https://platform.claude.com/docs/zh-TW/api/claude-models-on-google-cloud-anthropic-managed-iam-permissions)。
#### 請求 ID
Claude Models on Google Cloud (Anthropic managed) 的成功回應會攜帶 [`request-id`](https://platform.claude.com/docs/zh-TW/api/errors#request-id) 標頭。
## 從既有的 Anthropic 組織遷移
您無法將既有的 Anthropic 組織轉換為 Claude Models on Google Cloud (Anthropic managed) 的組織，包括您直接搭配 Claude API 使用的組織。
請將遷移規劃為切換至新組織：
* **先建立新組織。** 依照[設定您的帳戶](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#set-up-your-account)操作。
* **重新建立存取權限與設定。** API 金鑰、工作區及 Claude Console 設定不會延續。請在專案上授予 [IAM 角色](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#iam-roles)，而非建立 API 金鑰。若要重新建立工作區，請參閱[工作區](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#workspaces)。關於 ZDR 安排，請參閱[資料保留](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#data-retention)。
* **規劃已儲存的資源。** 檔案、技能、批次及 Claude Managed Agents 資源會保留在既有組織中。
* **更新您的整合。** 關於哪些會變更、哪些保持不變，請參閱[發送請求](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#making-requests)。關於不受支援的功能，請參閱[不支援的功能](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#features-not-supported)。
* **依您自己的時程切換。** 兩個組織彼此獨立，可以並行處理流量。您可以逐步遷移工作負載。既有組織會維持其目前的計費方式。在轉移正式環境流量之前，請檢查[速率限制](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#rate-limits)。
## 從 Claude Models on Google Cloud (Google managed) 遷移
若要改用 Claude Models on Google Cloud (Anthropic managed)，請完成以下步驟。在遷移依賴 ZDR 安排的工作負載之前，請參閱[資料保留](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#data-retention)。關於遷移時會有哪些變化，請參閱[兩種 Google Cloud 方案的差異](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/overview#how-the-two-google-cloud-offerings-differ)。
完成[設定您的帳戶](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#set-up-your-account)中的每個步驟。
將 `roles/claude.user` 授予每個呼叫 Claude Models on Google Cloud (Anthropic managed) 的身分。將您的專案和工作區 ID 設定為環境變數。關於這兩項，請參閱[進行 API 呼叫之前](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#before-making-api-calls)。
安裝提供 Claude Models on Google Cloud (Anthropic managed) 用戶端的套件。請參閱[安裝 SDK](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#install-an-sdk)。
修改匯入並建立用戶端的程式碼。使用 `AnthropicGoogleCloud` (csharp: `AnthropicGoogleCloudClient`; go: `googlecloud.NewClient`; java: `GoogleCloudBackend`; php: `Anthropic\GoogleCloud\Client`; ruby: `Anthropic::GoogleCloudClient`) 取代 `AnthropicVertex` (csharp: `AnthropicVertexClient`; go: `vertex.WithGoogleAuth`; java: `VertexBackend`; php: `Anthropic\Vertex\Client`; ruby: `Anthropic::VertexClient`)。在 cURL 請求中，請修改 URL、標頭和主體。您目前的程式碼會建立 Claude Models on Google Cloud (Google managed) 的用戶端。例如，以下程式碼使用全域端點建立該用戶端：
```bash cURL
curl https://aiplatform.googleapis.com/v1/projects/MY_PROJECT_ID/locations/global/publishers/anthropic/models/claude-opus-5-5:rawPredict \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
"anthropic_version": "vertex-2023-10-16",
"messages": [{"role": "user", "content": "Hey Claude!"}],
"max_tokens": 100
}'
```
`ant` CLI 不支援 Claude Models on Google Cloud (Google managed)。
```python Python
from anthropic import AnthropicVertex
project_id = "MY_PROJECT_ID"
region = "global"
client = AnthropicVertex(project_id=project_id, region=region)
```
```typescript TypeScript
import { AnthropicVertex } from "@anthropic-ai/vertex-sdk";
const projectId = "MY_PROJECT_ID";
const region = "global";
const client = new AnthropicVertex({
projectId,
region
});
```
```csharp C#
using Anthropic.Vertex;
var projectId = "MY_PROJECT_ID";
var region = "global";
var client = new AnthropicVertexClient(new AnthropicVertexCredentials(region, projectId));
```
```go Go
import (
"context"
"github.com/anthropics/anthropic-sdk-go"
"github.com/anthropics/anthropic-sdk-go/vertex"
)
// ...
// 使用預設的 Google Cloud 憑證
client := anthropic.NewClient(
vertex.WithGoogleAuth(context.Background(), "global", "MY_PROJECT_ID"),
)
```
```java Java
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.vertex.backends.VertexBackend;
import com.google.auth.oauth2.GoogleCredentials;
void main() throws Exception {
AnthropicClient client = AnthropicOkHttpClient.builder()
.backend(
VertexBackend.builder()
.googleCredentials(GoogleCredentials.getApplicationDefault())
.region("global")
.project("MY_PROJECT_ID")
.build()
)
.build();
}
```
```php PHP
use Anthropic\Vertex;
$client = Vertex\Client::fromEnvironment(
region: 'global',
projectId: 'MY_PROJECT_ID',
);
```
```ruby Ruby
require "anthropic"
client = Anthropic::VertexClient.new(
region: "global",
project_id: "MY_PROJECT_ID"
)
```
以下程式碼會建立 Claude Models on Google Cloud (Anthropic managed) 的用戶端：
```bash cURL
curl "https://claude.googleapis.com/v1/projects/$ANTHROPIC_GOOGLE_CLOUD_PROJECT/locations/global/workspaces/$ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID/invoke/v1/messages" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "content-type: application/json" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, Claude"}
]
}'
```
```bash CLI
ant messages create \
--model claude-opus-5-5 \
--max-tokens 1024 \
--message '{role: user, content: "Hello, Claude"}'
```
```python Python
from anthropic import AnthropicGoogleCloud
client = AnthropicGoogleCloud()
```
```typescript TypeScript
import { AnthropicGoogleCloud } from "@anthropic-ai/google-cloud-sdk";
const client = new AnthropicGoogleCloud();
```
```csharp C#
using Anthropic.GoogleCloud;
var client = new AnthropicGoogleCloudClient();
```
```go Go
import (
"context"
"github.com/anthropics/anthropic-sdk-go"
"github.com/anthropics/anthropic-sdk-go/googlecloud"
)
// ...
client, err := googlecloud.NewClient(context.Background(), googlecloud.ClientConfig{})
if err != nil {
panic(err)
}
```
```java Java
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.googlecloud.backends.GoogleCloudBackend;
void main() {
AnthropicClient client = AnthropicOkHttpClient.builder()
.backend(GoogleCloudBackend.fromEnv())
.build();
}
```
```php PHP
use Anthropic\GoogleCloud\Client;
$client = new Client();
```
```ruby Ruby
require "anthropic"
client = Anthropic::GoogleCloudClient.new
```
新的用戶端會從您在[尋找您的工作區 ID](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#find-your-workspace-id) 中設定的環境變數讀取您的專案和工作區 ID。建立用戶端時不需要傳入這些值。您的 Messages API 呼叫維持不變，但下一步中的模型 ID 和功能除外。
* **模型 ID：** 如果您使用早於 Claude 4.6 的模型，請將其 ID 中快照日期前的 `@` 替換為連字號。例如，`claude-haiku-4-5@20251001` 會變成 `claude-haiku-4-5-20251001`。關於模型及其 ID，請參閱 [API 模型 ID](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#api-model-ids)。
* **功能：** 針對您的程式碼使用的每項功能，請查看[功能支援](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#feature-support)。
* **位置：** 如果您目前使用多區域或區域端點，請確認 Claude Models on Google Cloud (Anthropic managed) 使用哪個位置。請參閱[專案、位置與工作區解析](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution)。
執行[發出請求](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#making-requests)中的請求，以確認您的設定可正常運作。接著執行您自己的程式碼。如果呼叫因權限錯誤而失敗，請參閱[帳戶設定疑難排解](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#troubleshooting-account-setup)。在遷移正式環境流量之前，請查看[速率限制](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#rate-limits)。
## 後續步驟
探索 Claude 的功能。
查詢權限、角色和稽核記錄類型。
隨著更安全、更強大的模型推出，Anthropic 會定期淘汰較舊的模型。查看所有 API 棄用項目及建議的替代方案。
管理您的訂閱和帳單。