OpenCode-Befehlszeile verwenden

OpenCode-Befehlszeile verwenden

Vorschau

Diese Funktion unterliegt den „Bedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA‑Funktionen stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie unter den Beschreibungen der Startphase.

Auf dieser Seite wird beschrieben, wie Sie die OpenCode-Befehlszeile (Command Line Interface, CLI) mit einer Gemini Enterprise Agent Platform Workbench-Instanz verwenden.

Dieses Dokument richtet sich an Datenanalysten, Data Scientists und Datenentwickler, die mit Agent Platform Workbench arbeiten. In diesem Dokument wird davon ausgegangen, dass Sie wissen, wie Sie Code in einer Notebook-Umgebung schreiben.

Übersicht

OpenCode ist ein Open-Source-KI-Coding-Agent, der in einem Terminal ausgeführt wird. Weitere Informationen finden Sie unter opencode.ai.

Wenn ein Administrator die OpenCode-Befehlszeile aktiviert, ist sie in einem Terminal in der JupyterLab-Oberfläche Ihrer Agent Platform Workbench-Instanz verfügbar. Sie können damit mit den Notebooks und Dateien auf Ihrer Instanz arbeiten sowie Shell-Befehle und Google Cloud -Befehle ausführen, indem Sie Anweisungen in natürlicher Sprache geben.

Beschränkungen

Beachten Sie die folgenden Einschränkungen, wenn Sie die OpenCode CLI mit der Agent Platform Workbench verwenden:

• OpenCode ist nur über die Befehlszeile verfügbar. Eine grafische Chatoberfläche und erweiterte Tools im Editor sind nicht enthalten.

• Wenn Sie OpenCode auffordern, ein Notebook zu ändern, ändert OpenCode die Notebook-Datei direkt auf der Festplatte der Instanz. Aus diesem Grund können Sie Änderungen, die von OpenCode vorgenommen wurden, nicht mit der Schaltfläche Rückgängig des Notebook-Editors oder mit Strg+Z (Befehlstaste+Z unter macOS) rückgängig machen. Sie können OpenCode jedoch bitten, eine Änderung mit einem Befehl in natürlicher Sprache wie Undo your last change rückgängig zu machen.

• Da OpenCode direkt auf die Festplatte schreibt, kann es eine Datei ändern, die Sie auch in JupyterLab geöffnet haben. Wenn Sie in einem Notebook nicht gespeicherte Änderungen haben, speichern Sie diese, bevor Sie OpenCode bitten, das Notebook zu ändern.

• OpenCode wird mit den Anmeldedaten ausgeführt, die in Ihrer Instanz aktiv sind. Standardmäßig sind das die Anmeldedaten des Dienstkontos Ihrer Agent Platform Workbench-Instanz. OpenCode kann also auf dieselben Ressourcen zugreifen wie die Instanz. Wenn Sie eine andere Identität in der Instanz authentifizieren (z. B. durch Ausführen von gcloud auth login oder gcloud auth application-default login), verwendet OpenCode stattdessen die Berechtigungen dieser Identität.

Hinweis

Da es sich bei Produkten von Gemini for Google Cloudum Technologie in einem frühen Entwicklungsstadium handelt, kann es zu Ergebnissen kommen, die zwar plausibel erscheinen, aber faktisch falsch sind. Ausgaben der Produkte von Gemini für Google Cloud sollten daher vor der Verwendung geprüft werden. Weitere Informationen finden Sie unter Gemini für Google Cloud und verantwortungsbewusste Anwendung von KI.

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

Erforderliche Rollen

Wenn Sie die OpenCode CLI in Agent Platform Workbench verwenden möchten, müssen Sie dem Nutzer der Agent Platform Workbench-Instanz und dem Dienstkonto der Instanz Berechtigungen erteilen.

Hinweis :OpenCode arbeitet ausschließlich innerhalb der Berechtigungen der Umgebung Ihrer Agent Platform Workbench-Instanz. Wenn Sie (oder das Dienstkonto, das von Ihrer Instanz verwendet wird) keine Berechtigung für den Zugriff auf eine bestimmte Ressource haben, kann OpenCode auch nicht darauf zugreifen. Wenn ein Befehl aufgrund von Berechtigungen fehlschlägt, bitten Sie Ihren Administrator, die erforderlichen Berechtigungen zu gewähren.

Dem Nutzer der Instanz Berechtigungen erteilen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Agent Platform User (roles/aiplatform.user) für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Verwenden der OpenCode CLI in einer Agent Platform Workbench-Instanz benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Dem Dienstkonto Ihrer Instanz eine Berechtigung gewähren

Damit das Dienstkonto Ihrer Agent Platform Workbench-Instanz die erforderliche Berechtigung hat, die OpenCode-Befehlszeile in einer Agent Platform Workbench-Instanz auszuführen, bitten Sie Ihren Administrator, dem Dienstkonto Ihrer Agent Platform Workbench-Instanz die IAM-Rolle Agent Platform User (roles/aiplatform.user) für das Projekt zu erteilen.

Wichtig:Sie müssen diese Rolle dem Dienstkonto Ihrer Agent Platform Workbench-Instanz und nicht Ihrem Nutzerkonto zuweisen. Wenn die Rolle nicht dem richtigen Hauptkonto zugewiesen wird, können Berechtigungsfehler auftreten.

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierte Rolle enthält die Berechtigung aiplatform.endpoints.predict, die zum Aktivieren der OpenCode CLI für die Ausführung in einer Agent Platform Workbench-Instanz erforderlich ist.

Ihr Administrator kann dem Dienstkonto Ihrer Agent Platform Workbench-Instanz möglicherweise auch diese Berechtigung mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erteilen.

OpenCode CLI aktivieren

Die OpenCode-Befehlszeile ist nur für Agent Platform Workbench-Instanzen verfügbar, für die das Debian 12-Image (workbench-instances-2603) verwendet wird. Sie ist nicht auf Instanzen installiert, die das Debian 11-Image (workbench-instances) verwenden.

Die OpenCode CLI ist auf unterstützten Instanzen standardmäßig aktiviert. Wenn Sie sie deaktivieren möchten, legen Sie den Instanzmetadatenschlüssel enable-opencode auf false fest. Weitere Informationen finden Sie unter Funktionen über Metadaten verwalten.

OpenCode-Befehlszeile verwenden

1. Rufen Sie in der Google Cloud Console die Seite Instanzen auf.

   Zur Seite „VM-Instanzen“

2. Klicken Sie neben dem Namen einer Agent Platform Workbench-Instanz auf JupyterLab öffnen.

3. Klicken Sie in JupyterLab auf Datei > Neuer Launcher.

4. Klicken Sie auf dem Tab Launcher im Bereich Andere auf die Kachel OpenCode.

   Ein Terminal wird geöffnet und die OpenCode CLI wird gestartet.

5. Geben Sie einen Prompt ein, z. B. „Erstelle ein neues Notebook mit dem Namen ‚test-notebook‘“.

6. Wenn OpenCode eine Aktion vorschlägt, z. B. eine Datei zu bearbeiten oder einen Shell-Befehl auszuführen, überprüfen Sie sie und genehmigen oder lehnen Sie sie ab. Weitere Informationen finden Sie unter Tool-Aktionen genehmigen.

Tool-Aktionen genehmigen

Standardmäßig fragt OpenCode in der Agent Platform Workbench Sie um Ihre Genehmigung, bevor Aktionen ausgeführt werden, z. B. das Bearbeiten einer Datei, das Ausführen eines Shell-Befehls oder das Abrufen einer URL. Prüfen Sie jeden Vorschlag, bevor Sie ihn genehmigen.

Diese Standardeinstellung schützt vor Prompt Injections. Ein Notebook, ein Skript oder eine Webseite, die von OpenCode gelesen werden, können verborgene Anweisungen enthalten, die den Agenten dazu bringen sollen, Befehle auszuführen, die Sie nicht beabsichtigt haben, z. B. das Senden Ihrer Daten an eine externe Adresse. Da OpenCode mit den Anmeldedaten Ihrer Instanz ausgeführt wird, haben Sie durch die erforderliche Genehmigung die Möglichkeit, eine solche Aktion zu sehen und zu stoppen, bevor sie ausgeführt wird.

Achtung :Sie können dieses Verhalten in Ihrer eigenen OpenCode-Konfiguration ändern und Genehmigungsaufforderungen auch vollständig deaktivieren. Wenn Sie dies tun, führt OpenCode Aktionen aus, ohne Sie vorher zu fragen. Sie akzeptieren das daraus resultierende Risiko von Prompt-Injection und Daten-Exfiltration für Ihre Arbeitslasten.

Drittanbietermodelle verwenden

Standardmäßig ist OpenCode in der Agent Platform Workbench so konfiguriert, dass nur die Gemini- und Claude-Modelle verwendet werden, die über die Gemini Enterprise Agent Platform in Ihrem Projekt bereitgestellt werden. Diese Anfragen werden mit den Anmeldedaten Ihrer Instanz für die Gemini Enterprise Agent Platform Ihres Projekts authentifiziert. Sie bleiben also in IhremGoogle Cloud -Projekt und unterliegen den dafür geltenden Sicherheitskontrollen.

OpenCode unterstützt auch Modellanbieter, deren Anfragen außerhalb Ihres Projekts gesendet werden. Dazu gehören Google AI Studio (die Gemini Developer API), die trotz der Gemini-Modelle ein separater Dienst ist, der mit einem persönlichen API-Schlüssel anstelle der Anmeldedaten Ihres Projekts authentifiziert wird, sowie Nicht-Google-Anbieter wie OpenAI und die direkten APIs von Anthropic. Alle diese Funktionen sind standardmäßig deaktiviert. Sie können einen aktivieren, indem Sie Ihre eigene OpenCode-Konfiguration bearbeiten und den API-Schlüssel des Anbieters angeben.

Warnung :Wenn Sie einen dieser Anbieter aktivieren, werden Ihre Prompts und alle darin enthaltenen Daten, einschließlich der Daten, die aus Ihren Notebooks und Dateien gelesen werden, an die externe API des Anbieters gesendet. Diese Daten verlassen die Grenzen Ihres Google Cloud -Projekts. Sie ist nicht mehr durch die Sicherheitskontrollen geschützt, die in Ihrem Projekt gelten, einschließlich des Model Armor-Schutzes vor Prompt Injections, sofern Sie ihn konfiguriert haben. Die Aktivierung eines solchen Anbieters liegt in Ihrem Ermessen und in Ihrer Verantwortung, einschließlich der Einhaltung aller Vereinbarungen zur Datenverarbeitung, die Sie mit diesem Anbieter getroffen haben.

Zugriff auf die OpenCode CLI steuern

Der Zugriff auf OpenCode wird durch zwei unabhängige Kontrollen geregelt: ob der OpenCode-Launcher angezeigt wird und ob die zugrunde liegenden Modelle aufgerufen werden können. Diese Einstellungen sind unabhängig voneinander. Wenn Sie den Launcher ausblenden, werden die Modelle nicht blockiert. Wenn Sie die Modelle einschränken, wird der Launcher nicht entfernt. Konfigurieren Sie daher beide Einstellungen entsprechend der Richtlinie Ihrer Organisation.

Steuern, ob der OpenCode-Launcher angezeigt wird

Mit dem Instanzmetadatenschlüssel enable-opencode können Sie steuern, ob OpenCode auf einer Instanz angeboten wird. OpenCode ist standardmäßig aktiviert: Die OpenCode-Kachel wird im JupyterLab-Launcher angezeigt, sofern ein Administrator den Schlüssel nicht auf false setzt, wodurch sie ausgeblendet wird.

Diese Einstellung steuert nur, ob der Launcher angezeigt wird. Dadurch wird der Zugriff auf die Modelle nicht blockiert. Ein Nutzer, der auf die Umgebung der Instanz zugreifen kann (z. B. über ein Terminal), kann OpenCode weiterhin starten und alle Modelle aufrufen, die er mit seinen Anmeldedaten verwenden darf. Wenn Sie einschränken möchten, was OpenCode tun kann, steuern Sie den Zugriff auf die Modelle, wie im nächsten Abschnitt beschrieben.

Zugriff auf die Modelle steuern

OpenCode ruft Modelle über die Gemini Enterprise Agent Platform mit den Anmeldedaten Ihrer Instanz auf. Dabei wird dieselbe Gemini Enterprise Agent Platform-Authentifizierung verwendet wie bei der Gemini CLI. Nutzer geben keinen API-Schlüssel ein, um die Standardmodelle von Gemini und Claude zu verwenden. Eine Anfrage ist nur erfolgreich, wenn die Identität der Instanz das Modell aufrufen darf und das Projekt Zugriff darauf hat. Mit dieser Einstellung wird festgelegt, ob OpenCode Antworten generieren kann. Sie gilt unabhängig davon, wie OpenCode gestartet wird.

Verwenden Sie zum Verwalten des Modellzugriffs dieselben Steuerelemente, die für jeden Client der Gemini Enterprise Agent Platform gelten:

• Wenn Sie bestimmte Modelle auf Organisations-, Ordner- oder Projektebene zulassen oder einschränken möchten, richten Sie eine Organisationsrichtlinie ein. Weitere Informationen finden Sie unter Zugriff auf Model Garden-Modelle steuern.

• Wenn Sie verhindern möchten, dass eine Identität Modellendpunkte für Inferenzen verwendet, gewähren Sie ihr nicht die Berechtigung aiplatform.endpoints.predict.

• Für Modelle von Anbietern außerhalb Ihres Projekts (z. B. die direkte API von Anthropic) muss der Nutzer den API-Schlüssel dieses Anbieters in seiner eigenen OpenCode-Konfiguration angeben. Sie sind standardmäßig deaktiviert. Weitere Informationen finden Sie unter Drittanbietermodelle verwenden.

Nächste Schritte

• Weitere Informationen zur Gemini Enterprise Agent Platform

• Informationen zum Festlegen von Instanzmetadaten finden Sie unter Features über Metadaten verwalten.