使用 OpenCode CLI

使用 OpenCode CLI

預覽

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前功能是依「原樣」提供，支援服務可能受限。 詳情請參閱推出階段說明。

本頁說明如何搭配 Gemini Enterprise Agent Platform Workbench 執行個體，使用 OpenCode 指令列介面 (CLI)。

本文適用於使用 Agent Platform Workbench 的資料分析師、資料科學家和資料開發人員。本文假設您瞭解如何在筆記本環境中編寫程式碼。

總覽

OpenCode 是開放原始碼的 AI 程式碼編寫代理程式，可在終端機中執行。詳情請參閱 opencode.ai。

管理員啟用後，您可以在 Agent Platform Workbench 執行個體 JupyterLab 介面的終端機中使用 OpenCode CLI。你可以使用自然語言提供指令，透過這項功能處理執行個體中的筆記本和檔案，以及執行殼層指令和 Google Cloud 指令。

限制

使用 OpenCode CLI 和 Agent Platform Workbench 時，請注意下列限制：

• OpenCode 僅適用於 CLI。不含圖形化聊天介面和進階編輯器內工具。

• 要求 OpenCode 修改筆記本時，OpenCode 會直接在執行個體的磁碟上變更筆記本檔案。因此，您無法使用筆記本編輯器的「復原」按鈕或 Control+Z 鍵 (macOS 上的 Command+Z 鍵)，復原 OpenCode 所做的編輯。不過，你可以使用自然語言指令 (例如 Undo your last change)，要求 OpenCode 復原變更。

• 由於 OpenCode 會直接寫入磁碟，因此可能會變更您在 JupyterLab 中開啟的檔案。如果筆記本中有尚未儲存的變更，請先儲存變更，再要求 OpenCode 修改該筆記本。

• OpenCode 會使用您執行個體上啟用的憑證執行。根據預設，這些是 Agent Platform Workbench 執行個體的服務帳戶憑證，因此 OpenCode 可以存取執行個體可存取的相同資源。如果您在執行個體上驗證其他身分 (例如執行 gcloud auth login 或 gcloud auth application-default login)，OpenCode 會改用該身分的權限。

事前準備

Gemini for Google Cloud產品仍處於早期技術階段，因此可能會生成看似合理卻與事實不符的輸出內容。使用輸出內容前，請一律確認 Gemini for Google Cloud 產品輸出內容是否屬實。詳情請參閱「Gemini for Google Cloud 和負責任的 AI 技術」。

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Compute Engine, Notebooks, and Agent Platform APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Compute Engine, Notebooks, and Agent Platform APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

必要的角色

如要在 Agent Platform Workbench 中使用 OpenCode CLI，您必須授予 Agent Platform Workbench 執行個體使用者和執行個體服務帳戶權限。

注意： OpenCode 嚴格遵守 Agent Platform Workbench 執行個體環境的權限。如果您 (或執行個體使用的服務帳戶) 沒有存取特定資源的權限，OpenCode 也無法存取該資源。如果指令因權限問題而失敗，請要求管理員授予必要權限。

授予執行個體使用者權限

如要在 Agent Platform Workbench 執行個體中使用 OpenCode CLI，請要求管理員授予您專案的Agent Platform 使用者 (roles/aiplatform.user) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

將權限授予執行個體的服務帳戶

為確保 Agent Platform Workbench 執行個體的服務帳戶具備必要權限，可讓 OpenCode CLI 在 Agent Platform Workbench 執行個體中執行， 請管理員將專案的「Agent Platform 使用者」 (roles/aiplatform.user) IAM 角色授予 Agent Platform Workbench 執行個體的服務帳戶。

重要事項：您必須將這個角色授予 Agent Platform Workbench 執行個體的服務帳戶，而非使用者帳戶。如果未將角色授予正確的主體，可能會導致權限錯誤。

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

這個預先定義的角色具備 aiplatform.endpoints.predict 權限，可讓 OpenCode CLI 在 Agent Platform Workbench 執行個體中執行。

管理員或許還可透過自訂角色或其他預先定義的角色，為 Agent Platform Workbench 執行個體的服務帳戶授予這項權限。

啟用 OpenCode CLI

OpenCode CLI 僅適用於使用 Debian 12 (workbench-instances-2603) 映像檔的 Agent Platform Workbench 執行個體。使用 Debian 11 (workbench-instances) 映像檔的執行個體不會安裝。

在支援的執行個體上，OpenCode CLI 預設為開啟。如要關閉，請將 enable-opencode 執行個體中繼資料鍵設為 false。詳情請參閱「透過中繼資料管理功能」。

使用 OpenCode CLI

1. 前往 Google Cloud 控制台的「Instances」(執行個體) 頁面。

   前往「Instances」(執行個體)

2. 按一下 Agent Platform Workbench 執行個體名稱旁的「Open JupyterLab」(開啟 JupyterLab)。

3. 在 JupyterLab 中，依序點選「File」>「New launcher」。

4. 在「啟動器」分頁的「其他」部分，按一下「OpenCode」圖塊。

   終端機會開啟並啟動 OpenCode CLI。

5. 輸入提示，例如「建立名為『test-notebook』的新筆記本」。

6. OpenCode 提出動作建議 (例如編輯檔案或執行 Shell 命令) 時，請先檢查，然後核准或拒絕。詳情請參閱「核准工具動作」。

核准工具動作

根據預設，Agent Platform Workbench 中的 OpenCode 會先徵求您的同意，再執行任何動作，例如編輯檔案、執行 Shell 指令或擷取網址。請先檢查每個建議動作，再核准。

這項預設設定可防範提示詞注入。OpenCode 讀取的筆記本、指令碼或網頁可能含有隱藏指令，試圖讓代理程式執行您不想要的指令，例如將資料傳送至外部地址。由於 OpenCode 會使用執行個體的憑證執行，因此需要核准才能執行，讓您有機會在動作執行前查看並停止這類動作。

注意： 您可以在自己的 OpenCode 設定中變更這項行為，包括完全關閉核准提示。如果這麼做，OpenCode 會在未事先詢問的情況下執行動作，而您也接受工作負載可能因此遭受提示詞注入和資料外洩的風險。

使用第三方模型

根據預設，Agent Platform Workbench 中的 OpenCode 只會使用專案中透過 Gemini Enterprise Agent Platform 提供的 Gemini 和 Claude 模型。這些要求會根據專案本身的 Gemini Enterprise Agent Platform，使用您執行個體的憑證進行驗證，因此會保留在您的Google Cloud 專案中，並繼續受到適用於該專案的安全控管機制約束。

OpenCode 也支援要求傳送至專案外部的模型供應商。包括 Google AI Studio (Gemini 開發人員 API)，雖然提供 Gemini 模型，但這是獨立服務，使用個人 API 金鑰而非專案憑證進行驗證，以及 OpenAI 和 Anthropic 直接 API 等非 Google 供應商。這些功能預設為關閉。如要啟用其中一個，請編輯自己的 OpenCode 設定，並提供供應商的 API 金鑰。

警告： 啟用其中一個供應商後，系統會將提示和其中包含的所有資料 (包括從筆記本和檔案讀取的資料) 傳送至該供應商的外部 API。這項資料會離開專案範圍。 Google Cloud 不再受專案內適用的安全控制項保護，包括Model Armor 提示詞注入防護 (如已設定)。啟用這類供應商是您的決定和責任，包括遵守您與該供應商簽訂的任何資料處理協議。

控管 OpenCode CLI 的存取權

OpenCode 的存取權由兩項獨立控制項管理：是否顯示 OpenCode 啟動器，以及是否可呼叫基礎模型。這兩者是分開的，隱藏啟動器不會封鎖模型，限制模型也不會移除啟動器，因此請一併設定兩者，以符合貴機構的政策。

控制是否顯示 OpenCode 啟動器

如要控管執行個體是否提供 OpenCode，請使用 enable-opencode 執行個體中繼資料金鑰。OpenCode 預設為開啟：除非管理員將金鑰設為 false (隱藏 OpenCode)，否則 JupyterLab 啟動器會顯示 OpenCode 圖塊。

這項設定只會控制是否顯示啟動器。這項設定本身不會封鎖模型存取權：如果使用者可以存取執行個體的環境 (例如透過終端機)，仍可啟動 OpenCode 並呼叫憑證允許使用的任何模型。如要限制 OpenCode 的功能，請按照下一節的說明控管模型存取權。

控管模型的存取權

OpenCode 會透過 Gemini Enterprise Agent Platform，使用您執行個體的憑證呼叫模型，也就是 Gemini CLI 使用的 Gemini Enterprise Agent Platform 驗證。使用者不必輸入 API 金鑰，即可使用預設的 Gemini 和 Claude 模型；只有在執行個體的 ID 獲准呼叫模型，且專案有權存取模型時，要求才會成功。這項控制選項可決定 OpenCode 是否能生成回覆，且無論 OpenCode 的啟動方式為何，這項設定都會生效。

如要管理模型存取權，請使用適用於任何 Gemini Enterprise Agent Platform 用戶端的相同控制選項：

• 如要在機構、資料夾或專案層級允許或限制特定模型，請設定機構政策。請參閱「控管 Model Garden 模型存取權」。

• 如要禁止身分使用模型端點進行推論，請勿授予 aiplatform.endpoints.predict 權限。

• 如果模型來自專案外部的供應商 (例如 Anthropic 的直接 API)，使用者必須在自己的 OpenCode 設定中提供該供應商的 API 金鑰，且預設為關閉。詳情請參閱「使用第三方模型」。

後續步驟

• 進一步瞭解 Gemini Enterprise Agent Platform。

• 如要瞭解如何設定執行個體中繼資料，請參閱「透過中繼資料管理功能」。