附註：這組說明文件適用於 Gemini Enterprise 的 Standard、Plus、即付即用和 Frontline 版本。如需 Business 版說明文件，請參閱 Gemini Enterprise - Business 版說明中心。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

設定 Google Antigravity 企業閘道

本文件說明管理員和資安架構師如何部署及設定 Google Antigravity 的企業閘道。

受監管產業中的企業組織通常會維持嚴格的網路控管，防止開發人員工作站直接連上網際網路，連至外部服務或完成互動式瀏覽器 Google 登入。

Antigravity Enterprise Gateway 可讓您透過貴組織營運的企業閘道轉送 Antigravity 流量，再將推論要求轉送至 Google。這個架構會透過閘道轉送模型推論要求，並移除互動式登入，同時保留 Gemini Enterprise 合約帳單歸屬。

總覽

設定 Antigravity Enterprise Gateway 後，開發人員工作站會與企業閘道通訊，而非直接連線至 Google。開發人員會使用閘道核發的 API 金鑰向閘道進行驗證，因此 Antigravity 不會提示他們登入個別 Google 帳戶。接著，閘道會使用集中式Google Cloud 服務帳戶，驗證 Antigravity 要求並轉送至 Google。

Antigravity 會自動附加用戶端歸因標頭，以識別開發人員對話提示和 Agentic Workflows。為確保系統能辨識這項模型用量，並根據貴組織現有的 Gemini Enterprise 協議計費，而非視為未承諾的原始 API 消耗量計費，閘道必須保留並將下列 Antigravity 標頭轉送至 Google：

User-Agent：Antigravity 會自動發出識別標頭：

User-Agent: antigravity/VERSION (aidev_client; auth_method=gateway)

X-Goog-Api-Client：識別 Antigravity 用戶端執行階段和 SDK 遙測，以便 Google 將活動歸功於您授權的企業部署。

支援的工具和版本

Antigravity Enterprise Gateway 支援下列 AI 開發人員工具：

工具	最低版本	支援的平台
Antigravity 應用程式	2.15.0 以上版本	macOS、Windows 和 Linux
Antigravity CLI (`agy`)	1.2.15 以上版本	macOS 和 Linux
IDE 適用的 Antigravity	Visual Studio Code 和 Visual Studio：Antigravity CLI 1.2.15 以上版本，擴充功能會自動下載及更新。 JetBrains IDE 和 Zed (含 ACP 伺服器)：1.3.0 以上版本	Visual Studio Code、Visual Studio、JetBrains IDE 和 Zed。詳情請參閱「Antigravity IDE 擴充功能」。

事前準備

部署閘道前，請確認您具備下列項目：

Google Cloud 雲端專案：可存取 Gemini Enterprise Agent Platform (原稱 Vertex AI) 的 Google Cloud 雲端專案，且已啟用 Gemini Enterprise Agent Platform API (aiplatform.googleapis.com)。部署企業閘道時，不需使用可開立月結單的 Cloud Billing 帳戶。凡是能存取 Gemini Enterprise Agent Platform 的使用者，都能使用這個閘道。
服務帳戶：專案中已授予 roles/aiplatform.user IAM 角色的 Google Cloud 服務帳戶。閘道會使用這個服務帳戶，驗證向 Google Cloud提出的 Antigravity 要求。
資料存取稽核記錄：如要在 Cloud Logging 中驗證帳單歸屬，請啟用 Gemini Enterprise Agent Platform API 的資料存取稽核記錄。詳情請參閱「啟用資料存取稽核記錄」。
支援的用戶端版本：開發人員必須使用各項 Antigravity 工具的支援版本。詳情請參閱「支援的 Antigravity 工具」。

部署企業閘道

您可以使用任何容器化或代管平台託管企業閘道，例如 Cloud Run、Envoy、LiteLLM 或 Apigee。

閘道必須符合三項基礎架構規定：

保留用戶端歸因標頭：將傳入的用戶端標頭原封不動轉送至 Google，包括 User-Agent、X-Goog-Api-Client，以及在 gateway.customHeaders 中設定的任何自訂標頭 (例如 X-Cost-Center)。

Antigravity 用戶端在閘道模式下不會傳送 Google Cloud 專案資訊。如果閘道將要求轉送至其他專案 (非閘道服務帳戶所在的專案)，請設定閘道，插入含有目標專案 ID 的 X-Goog-User-Project 標頭，以便歸屬帳單和配額。
支援無緩衝串流：處理串流要求 (:streamGenerateContent?alt=sse) 時，立即清除伺服器傳送事件 (SSE) 區塊。請勿在閘道層緩衝處理區塊。
確認遙測端點：以 HTTP 200 OK ({}) 回應背景指標呼叫 (POST /v1beta:*)，或將其轉送至安全資訊與事件管理 (SIEM) 系統。

必要要求路徑

閘道必須轉送下列推論路徑。路徑是相對於閘道網址。例如，傳送至 https://gateway.cymbal.com 的串流要求會使用 https://gateway.cymbal.com/v1beta/models/MODEL_ID:streamGenerateContent?alt=sse。

串流推論： POST /v1beta/models/MODEL_ID:streamGenerateContent?alt=sse
一元推論： POST /v1beta/models/MODEL_ID:generateContent

閘道也必須接受對等的完整 Gemini Enterprise Agent Platform 路徑：

串流推論： POST /v1beta1/projects/PROJECT_ID/locations/REGION/publishers/google/models/MODEL_ID:streamGenerateContent?alt=sse
一元推論： POST /v1beta1/projects/PROJECT_ID/locations/REGION/publishers/google/models/MODEL_ID:generateContent

要求主體使用標準 generateContent JSON 結構定義 (contents、generationConfig、safetySettings 和 systemInstruction)。

支援的線路通訊協定

Antigravity Enterprise Gateway 支援兩種推論要求線路通訊協定：

Gemini 通訊協定 (genai)：預設線路通訊協定。Antigravity 會將採用 Google generateContent 結構定義格式的推論要求，傳送至先前所述的 POST /v1beta/models/... 端點。
OpenAI 有線通訊協定 (openai)：將 gateway.wireProtocol 設為 openai (或設定 AGY_LLM_GATEWAY_WIRE_PROTOCOL=openai) 時，Antigravity 會以 OpenAI Chat Completions 通訊協定格式化推論要求，並傳送至 POST /v1/chat/completions。

驗證傳送至閘道的要求

Antigravity 會使用閘道核發的 API 金鑰，向閘道進行驗證。Antigravity 會將 gateway.apiKey (或 AGY_LLM_GATEWAY_API_KEY 環境變數) 中的金鑰，以不記名權杖的形式傳送至 Authorization 標頭：

Authorization: Bearer GATEWAY_API_KEY

Antigravity 不會代表開發人員取得 Google Cloud 憑證、OAuth 權杖或用戶端憑證。閘道必須驗證每項要求，並拒絕未提供有效金鑰的要求。

由於 API 金鑰儲存在開發人員工作站上，請搭配使用網路層級控制項：

保持閘道不公開：僅在公司網路上公開閘道，例如透過內部應用程式負載平衡器，讓工作站透過 Cloud VPN 或 Cloud Interconnect 存取。請勿為閘道提供公開端點。
限制可連線的裝置：僅允許從代管工作站連線，例如使用防火牆規則、零信任網路存取 Proxy 或裝置安全狀態檢查。
保護及輪替金鑰：將金鑰儲存在 Secret Manager 中、在每次要求時驗證金鑰，並定期輪替金鑰。如要將用量歸因於個別開發人員，請為每位開發人員核發專屬金鑰。

詳情請參閱「安全性考量」。

將閘道連結至 Gemini Enterprise Agent Platform

閘道會使用 Google Cloud 服務帳戶呼叫 Gemini Enterprise Agent Platform API。您可以在 Apigee 等代管 API 閘道上建構閘道，或在自己的基礎架構上部署 Envoy 或 LiteLLM 等閘道。

啟用必要的 API：

gcloud services enable \
  aiplatform.googleapis.com \
  secretmanager.googleapis.com \
  --project=PROJECT_ID

將 PROJECT_ID 替換為 Google Cloud 專案 ID。

為閘道建立服務帳戶，並授予 roles/aiplatform.user 角色：

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --project=PROJECT_ID \
  --display-name="Antigravity Enterprise Gateway"

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

將 SERVICE_ACCOUNT_NAME 替換為服務帳戶名稱，例如 agy-gateway-sa。

產生閘道 API 金鑰，儲存在 Secret Manager，並讓服務帳戶讀取：

openssl rand -base64 32 | tr -d '\n' | gcloud secrets create SECRET_NAME \
  --project=PROJECT_ID \
  --data-file=-

gcloud secrets add-iam-policy-binding SECRET_NAME \
  --project=PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

將 SECRET_NAME 替換為密鑰名稱，例如 agy-gateway-api-key。您將這組金鑰發布至工作站，做為 admin_settings.json 中的 gateway.apiKey。

設定閘道執行下列操作：
- 以服務帳戶身分向 Gemini Enterprise Agent Platform 驗證。
- 從 Secret Manager 讀取 API 金鑰，並拒絕未提供金鑰的要求。
- 允許要求執行至少 60 分鐘，以免長時間的串流回應中斷。

如要在設定工作站前確認閘道是否正常運作，請參閱「直接測試閘道」一節。

使用 MDM 部署設定

如要集中設定開發人員工作站，請使用行動裝置管理 (MDM) 系統 (例如 Jamf、Microsoft Intune、Ansible 或 Google Workspace MDM) 部署 admin_settings.json 設定檔。

Antigravity 會從下列作業系統路徑讀取 admin_settings.json：

macOS： /Library/Application Support/Antigravity/admin_settings.json
Linux： /etc/antigravity/admin_settings.json
Windows： %ProgramData%\Antigravity\admin_settings.json

如要部署設定檔，請按照下列步驟操作：

建立 admin_settings.json 檔案，並加入閘道網址、API 金鑰和核准的模型。如需範例，請參閱「設定範例」。

在 MDM 系統中建立套件、政策或指令碼，將檔案複製到每個目標作業系統的路徑。請以管理員權限執行指令碼，讓檔案歸管理員帳戶所有，開發人員只能讀取，無法修改。例如，MDM 指令碼可以執行下列指令：

macOS

在殼層中，以管理員身分執行下列指令：

sudo mkdir -p "/Library/Application Support/Antigravity"
sudo install -m 644 -o root -g wheel admin_settings.json \
"/Library/Application Support/Antigravity/admin_settings.json"

Linux

在殼層中，以管理員身分執行下列指令：

sudo install -D -m 644 -o root -g root admin_settings.json \
/etc/antigravity/admin_settings.json

Windows

在 PowerShell 中，以管理員身分執行下列指令：

$dir = Join-Path $env:ProgramData "Antigravity"
# Remove any folder that a non-admin created first, so they can't keep ownership.
if (Test-Path $dir) { Remove-Item -Recurse -Force $dir }
New-Item -ItemType Directory -Path $dir | Out-Null
# Administrators own the folder; only admins and SYSTEM can write; users can read.
icacls $dir /setowner "*S-1-5-32-544"
icacls $dir /inheritance:r /grant:r "*S-1-5-32-544:(OI)(CI)F" "*S-1-5-18:(OI)(CI)F" "*S-1-5-32-545:(OI)(CI)RX"
Copy-Item admin_settings.json (Join-Path $dir "admin_settings.json")

這些指令可讓所有使用者讀取資料夾和檔案，但只有管理員可以寫入。

將套件或政策指派給使用 Antigravity 的裝置或裝置群組。
在工作站上重新啟動 Antigravity，載入新設定。
如要確認工作站是否連線至閘道，請參閱「驗證用戶端連線」。

設定優先順序

Antigravity 會從三個來源讀取閘道設定。如果多個來源定義了相同設定，則優先順序較高的來源會勝出：

管理員設定檔 (最高)：由 MDM 系統部署的 admin_settings.json。
環境變數：在工作站上設定的 AGY_LLM_GATEWAY_* 變數。詳情請參閱「將 Antigravity 連線至 Enterprise Gateway」。
使用者設定檔 (最低)：開發人員主資料夾中的 ~/.antigravity/settings.json。

設定會逐一合併。舉例來說，如果 admin_settings.json 設定閘道網址，但未設定 API 金鑰，Antigravity 會使用環境變數中的 API 金鑰。由於管理員設定檔的優先順序最高，因此開發人員無法覆寫您在其中設定的值。

設定範例

以下 admin_settings.json 檔案範例會設定 Antigravity，透過 https://gateway.cymbal.com 的企業閘道路由 AI 流量、附加企業成本中心標頭，並將模型選取範圍限制為核准的模型：

{
  "gateway": {
    "enabled": true,
    "url": "https://gateway.cymbal.com",
    "apiKey": "GATEWAY_API_KEY",
    "wireProtocol": "genai",
    "customHeaders": {
      "X-Cost-Center": "Platform-Engineering",
      "X-Corporate-BU": "DevTools"
    }
  },
  "caCertPath": "/etc/ssl/certs/cymbal-root-ca.pem",
  "models": {
    "defaultModelId": "gemini-3.8-flash",
    "list": [
      { "modelId": "gemini-3.8-flash" },
      { "modelId": "gemini-3.7-flash" },
      { "modelId": "gemini-3.1-pro-preview" }
    ]
  }
}

這個設定範例定義了下列設定：

gateway.enabled：啟用閘道路由模式。設為 true 時，Antigravity 會將所有推論要求傳送至閘道，而非直接傳送至 Google，且不會提示開發人員使用 Google 帳戶登入。
gateway.url：企業閘道的 HTTPS 端點 (https://gateway.cymbal.com)。
gateway.apiKey：閘道用於授權要求的 API 金鑰 (GATEWAY_API_KEY)。這組金鑰是由閘道核發，而非 Google。Antigravity 會在 Authorization 標頭中以不記名權杖的形式傳送。
gateway.wireProtocol：API 有線通訊協定。支援的值如下：
- genai (預設)：使用 Gemini API 通訊協定 (POST /v1beta/models/...)。
- openai：使用 OpenAI Chat Completions 有線通訊協定 (POST /v1/chat/completions)。
注意： JetBrains IDE 和 Zed 使用 ACP 伺服器，僅支援 genai 有線通訊協定。
gateway.customHeaders：Antigravity 新增至各項要求的自訂 HTTP 標頭 (X-Cost-Center 和 X-Corporate-BU)。您可以使用這些標頭，在閘道記錄或 SIEM 中將用量歸因於團隊或成本中心。
caCertPath：公司根憑證授權單位 (CA) 組合的絕對路徑。這項設定可確保工作站信任閘道的內部 TLS 憑證。
models.defaultModelId：Antigravity 預設選取的模型 (例如 gemini-3.8-flash)。
models.list：開發人員可在 Antigravity 中選取的核准模型。每個項目都需要與閘道提供的模型相符的 modelId。如需支援的 Google 模型清單，請參閱「支援的模型」。

安全性考量

規劃閘道驗證和歸因時，請考量下列事項：

用戶端提供的標頭不受信任：開發人員可控管自己的工作站，因此可以變更環境變數 (AGY_LLM_GATEWAY_HEADERS) 或使用者設定檔中設定的標頭。請勿依賴這些標頭進行攸關安全的稽核記錄或帳單歸因。
使用 MDM 固定標頭：如要防止開發人員覆寫歸因或政策標頭，請在 admin_settings.json 的 gateway.customHeaders 中定義這些標頭。admin_settings.json 中的值優先於環境變數和使用者設定。
在網路或傳輸層進行驗證：如要驗證開發人員身分或強制執行嚴格的成本中心歸因，請在網路或傳輸層驗證流量，例如使用相互 TLS (mTLS)、Proxy 層級單一登入 (SSO) 或網路微區隔。請勿只依賴 API 金鑰或 HTTP 標頭。

驗證 Deployment

將設定檔部署至開發人員工作站前，請確認企業閘道能正確轉送流量，且歸因資訊會傳送至 Cloud Logging。

直接測試閘道

在開發人員工作站上測試之前，請先使用 curl 直接測試企業閘道端點。直接測試閘道，可確認網路路由、TLS 憑證驗證、驗證和未緩衝的伺服器傳送事件 (SSE) 串流，是否能獨立於 Antigravity 運作。

下列 curl 指令範例會直接將串流要求傳送至閘道端點：

curl -N -X POST "https://gateway.cymbal.com/v1beta/models/MODEL_ID:streamGenerateContent?alt=sse" \
  -H "Authorization: Bearer GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: antigravity/1.2.15 (aidev_client; auth_method=gateway)" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "Reply with PONG"}]}]}'

在這個指令中：

-N：關閉 curl 中的回應緩衝功能，以便立即串流伺服器傳送事件 (SSE)。
MODEL_ID：models.list 中核准的模型 (例如 gemini-3.8-flash 或 gemini-3.7-flash)。建議您先使用 Flash 模型進行測試，完成初步驗證。如要查看可用模型清單，請參閱「支援的模型」。
Authorization：傳送閘道 API 金鑰 (GATEWAY_API_KEY)，向閘道驗證要求。
User-Agent：傳送用戶端歸因字串，Google 會使用該字串將用量歸因至您的 Gemini Enterprise 協議。
streamGenerateContent?alt=sse：呼叫指定模型的串流 API 端點。

確認閘道會立即串流回應區塊。如果遇到連線錯誤、憑證警告或回應緩衝延遲，請參閱「疑難排解」。

驗證用戶端連線

在已設定的工作站上檢查用戶端狀態：

Antigravity 應用程式：確認底部狀態列的指標顯示「Connected: Enterprise Gateway」。在「Account Settings」中，確認顯示「Enterprise Gateway Mode Active」。
Antigravity CLI：執行測試提示詞：
```
agy -p "Explain binary search in Go"
```
這個指令會將測試提示傳送至閘道。確認回應在終端機中串流，且未顯示互動式 Google 登入提示。如果用戶端無法連線或提示 Google 驗證，請參閱「疑難排解」。

在 Cloud Logging 中驗證歸因

在 Google Cloud 控制台中，確認是否收到歸因標頭：

前往 Google Cloud 控制台的「Logs Explorer」頁面：

前往 Logs Explorer

執行以下查詢：

resource.type="aiplatform.googleapis.com/Endpoint" OR
protoPayload.serviceName="aiplatform.googleapis.com"

檢查記錄項目中繼資料。確認 protoPayload.requestMetadata.callerSuppliedUserAgent 包含 antigravity/VERSION (aidev_client; auth_method=gateway)。

如果沒有顯示任何記錄項目，請確認 Gemini Enterprise Agent Platform API 已啟用資料存取稽核記錄。

引導開發人員

驗證閘道後，請讓開發人員做好使用 Antigravity 的準備：

受管理的開發人員工作站：如果您使用 MDM 系統部署 admin_settings.json，開發人員就不需要執行任何設定。Antigravity 啟動時會自動連線至閘道。
沙箱和 CI/CD 管道：如果開發人員使用容器化執行器、遠端 SSH 主機或非代管開發環境，請提供閘道網址、API 金鑰和根 CA 路徑。請開發人員參閱「將 Antigravity 連線至 Enterprise Gateway」。

疑難排解

下表列出常見的部署問題和解決方法：

問題	原因	解析度
`x509: certificate signed by unknown authority`	工作站不信任閘道 TLS 憑證。	在 `admin_settings.json` 中使用 `caCertPath` 指定公司根 CA 組合的路徑。
`401 Unauthorized`或`403 Forbidden`	API 金鑰無效，或閘道服務帳戶沒有存取權。	請確認 `gateway.apiKey` 值，並確認閘道服務帳戶在目標專案中具備 `roles/aiplatform.user` IAM 角色。
`404 Not Found`	要求的模型不適用於企業閘道，或模型 ID 輸入錯誤。	確認 `admin_settings.json` 中 `models.list` 設定的每個模型 ID，都與企業閘道提供的模型名稱相符。
`gateway.wireProtocol 'openai' is not supported by the ACP server`	`admin_settings.json` 或環境變數指定了 ACP 伺服器不支援的 `openai` 網路通訊協定。	如果是 JetBrains IDE 和 Zed 工作站，請將 `wireProtocol` 設為 `genai` (或省略，使用預設值)。
串流回應逾時	閘道正在緩衝 HTTP 回應。	設定閘道，關閉伺服器傳送事件 (`text/event-stream`) 的回應緩衝功能。
Antigravity 提示登入 Google 帳戶	未開啟閘道模式，或 Antigravity 找不到設定檔。	確認 `admin_settings.json` 已部署至正確的作業系統路徑，且 `gateway` 區段包含 `"enabled": true` 和 `url`。

後續步驟

瞭解開發人員如何從遠端沙箱連線：將 Antigravity 連線至 Enterprise Gateway。
如要進一步瞭解 Antigravity 的功能和工作流程，請參閱 Antigravity 說明文件。
查看開發人員工具指標和用量：查看 AI 開發人員工具指標。
設定專案安全性政策：設定 AI 開發人員工具。