OpenCode CLI 사용

이 페이지에서는 Gemini Enterprise Agent Platform Workbench 인스턴스와 함께 OpenCode 명령줄 인터페이스 (CLI)를 사용하는 방법을 설명합니다.

이 문서는 Agent Platform Workbench를 사용하는 데이터 분석가, 데이터 과학자, 데이터 개발자를 대상으로 작성되었습니다. 이 문서에서는 노트북 환경에서 코드를 작성하는 방법을 알고 있다고 가정합니다.

개요

OpenCode는 터미널에서 실행되는 오픈소스 AI 코딩 에이전트입니다. 자세한 내용은 opencode.ai를 참고하세요.

관리자가 사용 설정하면 Agent Platform Workbench 인스턴스의 JupyterLab 인터페이스에 있는 터미널에서 OpenCode CLI를 사용할 수 있습니다. 자연어로 명령을 내려 인스턴스의 노트북과 파일을 사용하고 셸 명령어와 Google Cloud 명령어를 실행할 수 있습니다.

제한사항

Agent Platform Workbench에서 OpenCode CLI를 사용할 때는 다음 제한사항을 고려하세요.

  • OpenCode는 CLI 전용입니다. 그래픽 채팅 인터페이스와 고급 편집기 내 도구는 포함되지 않습니다.

  • OpenCode에 노트북 수정을 요청하면 OpenCode가 인스턴스의 디스크에서 노트북 파일을 직접 변경합니다. 따라서 노트북 편집기의 실행취소 버튼 또는 Control+Z (macOS에서는 Command+Z)를 사용하여 OpenCode에서 변경한 내용을 실행취소할 수 없습니다. 하지만 OpenCode에 Undo your last change와 같은 자연어 명령어를 사용하여 변경사항을 실행취소하도록 요청할 수 있습니다.

  • OpenCode는 디스크에 직접 쓰기 때문에 JupyterLab에서도 열려 있는 파일을 변경할 수 있습니다. 노트북에 저장되지 않은 변경사항이 있는 경우 OpenCode에 동일한 노트북을 수정해 달라고 요청하기 전에 변경사항을 저장하세요.

  • OpenCode는 인스턴스에서 활성화된 사용자 인증 정보로 실행됩니다. 기본적으로 이는 Agent Platform Workbench 인스턴스의 서비스 계정 사용자 인증 정보이므로 OpenCode는 인스턴스가 액세스할 수 있는 동일한 리소스에 액세스할 수 있습니다. 인스턴스에서 다른 ID를 인증하는 경우 (예: gcloud auth login 또는 gcloud auth application-default login 실행) OpenCode는 해당 ID의 권한을 대신 사용합니다.

시작하기 전에

  1. Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

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

  3. Verify that billing is enabled for your Google Cloud project.

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

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

  6. Verify that billing is enabled for your Google Cloud project.

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

    8.

필요한 역할

Agent Platform Workbench에서 OpenCode CLI를 사용하려면 Agent Platform Workbench 인스턴스의 사용자 및 인스턴스의 서비스 계정에 권한을 부여해야 합니다.

인스턴스 사용자에게 권한 부여

Agent Platform Workbench 인스턴스에서 OpenCode CLI를 사용하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Agent Platform 사용자 (roles/aiplatform.user) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

인스턴스의 서비스 계정에 권한 부여

Agent Platform Workbench 인스턴스의 서비스 계정에 Agent Platform Workbench 인스턴스에서 OpenCode CLI를 실행하는 데 필요한 권한이 있는지 확인하려면 관리자에게 프로젝트에서 Agent Platform Workbench 인스턴스의 서비스 계정에 Agent Platform 사용자 (roles/aiplatform.user) IAM 역할을 부여해 달라고 요청하세요.

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 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에서 파일 수정이나 셸 명령어 실행과 같은 작업을 제안하면 검토하고 승인하거나 거부합니다. 자세한 내용은 도구 작업 승인을 참고하세요.

도구 작업 승인

기본적으로 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 모델을 제공하지만 프로젝트 사용자 인증 정보가 아닌 개인 API 키로 인증하는 별도의 서비스인 Google AI Studio (Gemini Developer API)와 OpenAI 및 Anthropic의 직접 API와 같은 비Google 제공업체가 포함됩니다. 이러한 기능은 모두 기본적으로 사용 중지되어 있습니다. 자체 OpenCode 구성을 수정하고 제공업체의 API 키를 제공하여 하나를 사용 설정할 수 있습니다.

OpenCode CLI에 대한 액세스 제어

OpenCode 액세스는 OpenCode 런처 표시 여부와 기본 모델 호출 가능 여부라는 두 가지 독립적인 제어에 따라 관리됩니다. 이 두 가지는 별개이므로 런처를 숨겨도 모델이 차단되지 않고 모델을 제한해도 런처가 삭제되지 않습니다. 따라서 조직의 정책에 맞게 두 가지를 모두 구성하세요.

OpenCode 런처 표시 여부 제어

인스턴스에서 OpenCode가 제공되는지 여부를 제어하려면 enable-opencode 인스턴스 메타데이터 키를 사용하세요. OpenCode는 기본적으로 사용 설정되어 있습니다. 관리자가 키를 false로 설정하여 숨기지 않는 한 OpenCode 타일이 JupyterLab 런처에 표시됩니다.

이 설정은 런처가 표시되는지 여부만 제어합니다. 이 기능은 모델에 대한 액세스를 차단하지 않습니다. 인스턴스의 환경에 액세스할 수 있는 사용자 (예: 터미널을 통해)는 여전히 OpenCode를 시작하고 자신의 사용자 인증 정보로 사용할 수 있는 모델을 호출할 수 있습니다. OpenCode가 할 수 있는 작업을 제한하려면 다음 섹션에 설명된 대로 모델에 대한 액세스를 제어하세요.

모델에 대한 액세스 제어

OpenCode는 인스턴스의 사용자 인증 정보(Gemini CLI에서 사용하는 것과 동일한 Gemini Enterprise Agent Platform 인증)를 사용하여 Gemini Enterprise Agent Platform을 통해 모델을 호출합니다. 사용자는 기본 Gemini 및 Claude 모델을 사용하기 위해 API 키를 입력하지 않습니다. 인스턴스의 ID가 모델을 호출하도록 허용되고 프로젝트가 모델에 액세스할 수 있는 경우에만 요청이 성공합니다. 이 컨트롤은 OpenCode가 대답을 생성할 수 있는지 여부를 결정하며 OpenCode가 시작되는 방식에 관계없이 적용됩니다.

모델 액세스를 관리하려면 모든 Gemini Enterprise Agent Platform 클라이언트에 적용되는 것과 동일한 제어를 사용하세요.

  • 조직, 폴더 또는 프로젝트 수준에서 특정 모델을 허용하거나 제한하려면 조직 정책을 설정하세요. Model Garden 모델의 액세스 제어를 참고하세요.

  • 추론을 위해 모델 엔드포인트를 사용하지 못하도록 ID를 차단하려면 aiplatform.endpoints.predict 권한을 부여하지 마세요.

  • 프로젝트 외부 제공업체의 모델 (예: Anthropic의 직접 API)을 사용하려면 사용자가 자체 OpenCode 구성에 해당 제공업체의 API 키를 제공해야 하며 기본적으로 사용 중지되어 있습니다. 자세한 내용은 서드 파티 모델 사용을 참고하세요.

다음 단계