使用 OpenCode CLI

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

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

概览

OpenCode 是一款在终端中运行的开源 AI 编码智能体。如需了解详情，请参阅 opencode.ai。

管理员启用 OpenCode CLI 后，您可以在 Agent Platform Workbench 实例的 JupyterLab 界面中的终端内使用该 CLI。您可以使用它来处理实例上的笔记本和文件，并通过自然语言指令运行 shell 命令和 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 所需的权限，请让您的管理员为您授予项目的 Agent Platform User (roles/aiplatform.user) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

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

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

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

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

此预定义角色包含在 Agent Platform Workbench 实例中运行 OpenCode CLI 所需的 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. 在 Cloud de Confiance 控制台中，前往实例页面。

    转到“实例”

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

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

  4. 在启动器标签页的其他部分中，点击 OpenCode 块。

    系统会打开一个终端并启动 OpenCode CLI。

  5. 输入提示，例如“创建名为‘test-notebook’的新笔记本”。

  6. 当 OpenCode 建议执行某项操作（例如修改文件或运行 shell 命令）时，请查看并批准或拒绝该操作。如需了解详情，请参阅批准工具操作。

批准工具操作

默认情况下，Agent Platform Workbench 中的 OpenCode 在执行任何操作（例如修改文件、运行 shell 命令或提取网址）之前都会征求您的批准。在批准每项建议的操作之前，请先仔细检查。

此默认设置可防范提示词注入。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 默认处于开启状态：OpenCode 图块会显示在 JupyterLab 启动器中，除非管理员将该键设置为 false，这会将其隐藏。

此设置仅控制是否显示启动器。它本身不会阻止对模型的访问：可以访问实例环境（例如，通过终端）的用户仍然可以启动 OpenCode 并调用其凭据允许使用的任何模型。如需限制 OpenCode 的功能，请按照下一部分中的说明控制对模型的访问权限。

控制对模型的访问权限

OpenCode 使用实例的凭据（即 Gemini CLI 使用的 Gemini Enterprise Agent Platform 身份验证）通过 Gemini Enterprise Agent Platform 调用模型。用户无需输入 API 密钥即可使用默认的 Gemini 和 Claude 模型；只有在实例的身份有权调用模型且项目有权访问模型时，请求才会成功。此控件决定了 OpenCode 是否可以生成回答，并且无论 OpenCode 是如何启动的，此控件都适用。

如需管理模型访问权限，请使用适用于任何 Gemini Enterprise Agent Platform 客户端的相同控制措施：

  • 如需在组织、文件夹或项目级层允许或限制特定模型，请设置组织政策。请参阅控制对 Model Garden 模型的访问权限。

  • 如需阻止某个身份使用模型端点进行推理，请勿向其授予 aiplatform.endpoints.predict 权限。

  • 如果模型来自项目外部的提供商（例如 Anthropic 的直接 API），则用户需要在自己的 OpenCode 配置中提供该提供商的 API 密钥，并且这些模型默认处于关闭状态。如需了解详情，请参阅使用第三方模型。

后续步骤