使用 OpenCode CLI

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

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

總覽

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

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

限制

搭配使用 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 會改用該身分的權限。

事前準備

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance 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.

    Go to project selector

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. 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 執行個體的使用者和執行個體的服務帳戶。

將權限授予執行個體的使用者

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

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

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

為確保 Agent Platform Workbench 執行個體的服務帳戶具備必要權限，能在 Agent Platform Workbench 執行個體中執行 OpenCode CLI，請要求管理員將專案的 Agent Platform 使用者 (roles/aiplatform.user) IAM 角色授予 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. 前往 Cloud de Confiance 控制台的「Instances」(執行個體) 頁面。

    前往「Instances」(執行個體) 頁面

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

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

  4. 在「Launcher」分頁的「Other」部分，點選「OpenCode」圖塊。

    終端機隨即開啟，並啟動 OpenCode CLI。

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

  6. OpenCode 建議執行動作 (例如編輯檔案或執行殼層指令) 時，請查看並核准或拒絕。詳情請參閱「核准工具動作」。

核准工具動作

根據預設，Agent Platform Workbench 中的 OpenCode 會先徵求您的同意，再執行任何動作，例如編輯檔案、執行殼層指令或擷取網址。請先檢查每項提議的操作，再決定是否核准。

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

使用第三方模型

根據預設，Agent Platform Workbench 中的 OpenCode 僅會使用專案中透過 Gemini Enterprise Agent Platform 提供模型服務的 Gemini 和 Claude 模型。這些要求會使用執行個體的憑證，向專案自己的 Gemini Enterprise Agent Platform 進行驗證，因此會保留在Cloud de Confiance by S3NS 專案中，並受專案適用的安全控管機制規範。

OpenCode 也支援將要求傳送至專案外部的模型供應商。這包括 Google AI Studio (Gemini Developer API)，雖然提供 Gemini 模型，但屬於獨立服務，會使用個人 API 金鑰驗證，而非專案憑證。此外，也包括非 Google 供應商，例如 OpenAI 和 Anthropic 的直接 API。這些設定預設為關閉。如要啟用，請編輯自己的 OpenCode 設定，並提供供應商的 API 金鑰。

控管 OpenCode CLI 的存取權

OpenCode 的存取權由兩項獨立控制項控管：是否顯示 OpenCode 啟動器，以及是否可呼叫基礎模型。這兩項設定各自獨立，隱藏啟動器不會封鎖模型，限制模型也不會移除啟動器，因此請務必根據貴組織的政策進行設定。

控管是否顯示 OpenCode 啟動器

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

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

控管模型存取權

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

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

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

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

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

後續步驟