OpenCode CLI を使用する

このページでは、Gemini Enterprise Agent Platform Workbench インスタンスで OpenCode コマンドライン インターフェース（CLI）を使用する方法について説明します。

このドキュメントは、Agent Platform Workbench を使用するデータ アナリスト、データ サイエンティスト、データ デベロッパーを対象としています。このドキュメントは、ノートブック環境でコードを作成する方法を理解していることを前提としています。

概要

OpenCode は、ターミナルで実行されるオープンソースの AI コーディング エージェントです。詳細については、opencode.ai をご覧ください。

管理者が有効にすると、OpenCode CLI は Agent Platform Workbench インスタンスの JupyterLab インターフェースのターミナルで使用できるようになります。自然言語で指示することで、インスタンスのノートブックとファイルを操作したり、シェル コマンドと Google Cloud コマンドを実行したりできます。

制限事項

Agent Platform Workbench で OpenCode CLI を使用する場合は、次の制限事項を考慮してください。

  • OpenCode は CLI 専用です。グラフィカル チャット インターフェースと高度なエディタ内ツールは含まれません。

  • OpenCode にノートブックの変更をリクエストすると、OpenCode はインスタンスのディスク上のノートブック ファイルを直接変更します。そのため、ノートブック エディタの [元に戻す] ボタンまたは Control+Z（macOS の場合は Command+Z）を使用して、OpenCode によって行われた編集を元に戻すことはできません。ただし、Undo your last change などの自然言語コマンドを使用して、OpenCode に変更の取り消しをリクエストできます。

  • OpenCode はディスクに直接書き込むため、JupyterLab で開いているファイルも変更できます。ノートブックに保存されていない変更がある場合は、OpenCode に同じノートブックの変更を依頼する前に保存してください。

  • OpenCode は、インスタンスでアクティブな認証情報で実行されます。デフォルトでは、これらは Agent Platform Workbench インスタンスのサービス アカウントの認証情報であるため、OpenCode はインスタンスがアクセスできるリソースにアクセスできます。インスタンスで別の ID を認証した場合（gcloud auth login または gcloud auth application-default login を実行するなど）、OpenCode はその ID の権限を使用します。

始める前に

  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.

    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 インスタンスのユーザーとインスタンスのサービス アカウントに権限を付与する必要があります。

インスタンスのユーザーに権限を付与する

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 インスタンスのサービス アカウントに付与するよう管理者に依頼してください。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

この事前定義ロールには、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 で、[File] > [New launcher] をクリックします。

  4. [ランチャー] タブの [その他] セクションで、[OpenCode] タイルをクリックします。

    ターミナルが開き、OpenCode CLI が起動します。

  5. 「test-notebook という名前の新しいノートブックを作成して」などのプロンプトを入力します。

  6. OpenCode がファイル編集やシェル コマンドの実行などのアクションを提案した場合は、内容を確認して承認または拒否します。詳細については、ツールのアクションを承認するをご覧ください。

ツールのアクションを承認する

デフォルトでは、Agent Platform Workbench の OpenCode は、ファイルの編集、シェル コマンドの実行、URL の取得などの操作を行う前に、ユーザーの承認を求めます。提案されたアクションは、承認する前に必ず確認してください。

このデフォルトにより、プロンプト インジェクションから保護されます。OpenCode が読み取るノートブック、スクリプト、ウェブページには、エージェントに意図しないコマンド（外部アドレスへのデータの送信など）を実行させようとする隠れた指示が含まれている可能性があります。OpenCode はインスタンスの認証情報で実行されるため、承認を必須にすることで、実行前にこのようなアクションを確認して停止できます。

サードパーティ モデルを使用する

デフォルトでは、Agent Platform Workbench の OpenCode は、プロジェクトの Gemini Enterprise Agent Platform を介して提供される Gemini モデルと Claude モデルのみを使用するように構成されています。これらのリクエストは、プロジェクト独自の Gemini Enterprise Agent Platform に対してインスタンスの認証情報で認証されるため、Google Cloud プロジェクト内に留まり、適用されるセキュリティ制御の対象となります。

OpenCode は、リクエストがプロジェクト外に送信されるモデル プロバイダもサポートしています。これには、Gemini モデルを提供する Google AI Studio（Gemini Developer API）が含まれます。これは、プロジェクトの認証情報ではなく、個人用 API キーで認証する別のサービスです。また、OpenAI や Anthropic の直接 API などの Google 以外のプロバイダも含まれます。これらはすべてデフォルトでオフになっています。有効にするには、独自の OpenCode 構成を編集して、プロバイダの API キーを指定します。

OpenCode CLI へのアクセスを制御する

OpenCode へのアクセスは、OpenCode ランチャーが表示されるかどうかと、基盤となるモデルを呼び出すことができるかどうかという 2 つの独立した制御に則って管理されます。これらは別個のものです。ランチャーを非表示にしてもモデルはブロックされず、モデルを制限してもランチャーは削除されません。組織のポリシーに合わせて両方を構成してください。

OpenCode ランチャーを表示するかどうかを制御する

インスタンスで OpenCode を提供するかどうかを制御するには、enable-opencode インスタンス メタデータキーを使用します。OpenCode はデフォルトでオンになっています。管理者がキーを false に設定して非表示にしない限り、OpenCode タイルが JupyterLab ランチャーに表示されます。

この設定は、ランチャーを表示するかどうかのみを制御します。これ自体はモデルへのアクセスをブロックしません。インスタンスの環境にアクセスできるユーザー（ターミナルなど）は、引き続き OpenCode を起動し、認証情報で許可されているモデルを呼び出すことができます。OpenCode の機能を制限するには、次のセクションで説明するように、モデルへのアクセスを制御します。

モデルへのアクセスを制御する

OpenCode は、インスタンスの認証情報を使用して Gemini Enterprise Agent Platform を介してモデルを呼び出します。これは、Gemini CLI が使用する Gemini Enterprise Agent Platform の認証と同じです。ユーザーは、デフォルトの Gemini モデルと Claude モデルを使用するために API キーを入力しません。リクエストが成功するのは、インスタンスの ID がモデルの呼び出しを許可されており、プロジェクトがモデルにアクセスできる場合に限られます。この制御により、OpenCode がレスポンスを生成できるかどうかが決まります。この制御は、OpenCode の起動方法に関係なく適用されます。

モデルへのアクセスを管理するには、Gemini Enterprise Agent Platform クライアントに適用されるのと同じ制御を使用します。

  • 組織、フォルダ、プロジェクト レベルで特定のモデルを許可または制限するには、組織のポリシーを設定します。Model Garden モデルへのアクセスを制御するをご覧ください。

  • 推論にモデル エンドポイントを使用できないように ID をブロックするには、aiplatform.endpoints.predict 権限を付与しないでください。

  • プロジェクト外のプロバイダのモデル（Anthropic の直接 API など）では、ユーザーが独自の OpenCode 構成でそのプロバイダの API キーを指定する必要があります。デフォルトではオフになっています。詳細については、サードパーティ モデルを使用するをご覧ください。

次のステップ