使用 OpenCode CLI

使用 OpenCode CLI

预览

此功能受服务专用条款的“通用服务条款”部分中的“非正式版产品条款”的约束。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

本页面介绍了如何将 OpenCode 命令行界面 (CLI) 与 Gemini Enterprise Agent Platform Workbench 实例搭配使用。

本文档适用于使用 Agent Platform Workbench 的数据分析师、数据科学家和数据开发者。本文档假定您了解如何在笔记本环境中编写代码。

概览

OpenCode 是一款在终端中运行的开源 AI 编码代理。如需了解详情，请访问 opencode.ai。

管理员启用 OpenCode CLI 后，您可以在 Agent Platform Workbench 实例的 JupyterLab 界面中的终端中使用该 CLI。您可以使用它通过自然语言指令来处理实例中的笔记本和文件，并运行 shell 命令和 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 和 Responsible AI。

1. 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

2. Verify that billing is enabled for your Google Cloud 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 实例的用户和该实例的服务账号授予权限。

注意： OpenCode 严格在 Agent Platform Workbench 实例环境的权限范围内运行。如果您（或您的实例使用的服务账号）没有访问特定资源的权限，OpenCode 也无法访问该资源。如果命令因权限问题而失败，请让管理员授予必要的权限。

向实例用户授予权限

如需获得在 Agent Platform Workbench 实例中使用 OpenCode CLI 所需的权限，请让您的管理员为您授予项目的 Agent Platform User (roles/aiplatform.user) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

向实例的服务账号授予权限

如需确保您的 Agent Platform Workbench 实例的服务账号拥有必要的权限，以使 OpenCode CLI 能够在 Agent Platform Workbench 实例中运行，请让您的管理员为您的 Agent Platform Workbench 实例的服务账号授予项目的 Agent Platform User (roles/aiplatform.user) IAM 角色。

重要提示：您必须向 Agent Platform Workbench 实例的服务账号（而不是向您的用户账号）授予此角色。如果未能向正确的主账号授予此角色，可能会导致权限错误。

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色包含使 OpenCode CLI 能够在 Agent Platform Workbench 实例中运行所需的 aiplatform.endpoints.predict 权限。

您的管理员也可以使用自定义角色或其他预定义角色为 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 控制台中，前往实例页面。

   转到“实例”

2. 在 Agent Platform Workbench 实例名称旁边，点击打开 JupyterLab。

3. 在 JupyterLab 中，依次点击文件 > 新建启动器。

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 Developer API)，尽管它提供 Gemini 模型，但它是一项单独的服务，使用个人 API 密钥（而非项目的凭据）进行身份验证；此外还包括 OpenAI 和 Anthropic 的直接 API 等非 Google 提供商。默认情况下，所有这些设置都处于关闭状态。您可以通过修改自己的 OpenCode 配置并提供提供商的 API 密钥来启用其中一个。

警告： 如果您启用其中一个提供商，您的提示以及其中包含的所有数据（包括从笔记本和文件中读取的数据）都会发送到相应提供商的外部 API。这些数据会超出 Google Cloud 项目的范围。它不再受适用于您项目的安全控制措施的保护，包括模型装甲针对提示注入的保护（如果您已配置）。 启用此类提供商是您自己的决定，您需要自行承担相应责任，

包括遵守您与该提供商签订的任何数据处理协议。

控制对 OpenCode CLI 的访问权限

对 OpenCode 的访问权限由两项独立控制措施来管理：是否显示 OpenCode 启动器，以及是否可以调用底层模型。这两者是分开的，隐藏启动器不会屏蔽模型，限制模型也不会移除启动器，因此请同时配置这两者，以符合组织的政策。

控制 OpenCode 启动器是否显示

如需控制是否在实例上提供 OpenCode，请使用 enable-opencode 实例元数据键。OpenCode 默认处于开启状态：除非管理员将该键设置为 false（这会隐藏 OpenCode），否则 OpenCode 图块会显示在 JupyterLab 启动器中。

此设置仅控制是否显示启动器。它本身不会阻止对模型的访问：能够访问实例环境（例如通过终端）的用户仍然可以启动 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 密钥，并且默认处于关闭状态。如需了解详情，请参阅使用第三方模型。

后续步骤

• 详细了解 Gemini Enterprise Agent Platform。

• 如需了解如何设置实例元数据，请参阅通过元数据管理功能。