메인 콘텐츠로 건너뛰기

​
Google (Gemini)

Google Plugin은 Google AI Studio를 통한 Gemini 모델 액세스와 함께, Gemini Grounding을 통한 이미지 생성, 미디어 이해(이미지/오디오/비디오), 웹 검색을 제공합니다.
  • Provider: google
  • Auth: GEMINI_API_KEY 또는 GOOGLE_API_KEY
  • API: Google Gemini API
  • 대체 provider: google-gemini-cli (OAuth)

​
시작하기

선호하는 인증 방법을 선택하고 설정 단계를 따르세요.
가장 적합한 경우: Google AI Studio를 통한 일반적인 Gemini API 액세스.
1

온보딩 실행

openclaw onboard --auth-choice gemini-api-key
또는 키를 직접 전달할 수 있습니다:
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY"
2

기본 모델 설정

{
  agents: {
    defaults: {
      model: { primary: "google/gemini-3.1-pro-preview" },
    },
  },
}
3

모델 사용 가능 여부 확인

openclaw models list --provider google
환경 변수 GEMINI_API_KEY와 GOOGLE_API_KEY는 모두 허용됩니다. 이미 구성해 둔 값을 사용하세요.

​
기능

CapabilitySupported
Chat completionsYes
Image generationYes
Music generationYes
Image understandingYes
Audio transcriptionYes
Video understandingYes
Web search (Grounding)Yes
Thinking/reasoningYes (Gemini 3.1+)
Gemma 4 modelsYes
Gemma 4 모델(예: gemma-4-26b-a4b-it)은 thinking 모드를 지원합니다. OpenClaw는 Gemma 4에 대해 thinkingBudget를 지원되는 Google thinkingLevel로 재작성합니다. thinking을 off로 설정하면 MINIMAL로 매핑하지 않고 thinking 비활성화 상태를 유지합니다.

​
이미지 생성

번들 google 이미지 생성 provider의 기본값은 google/gemini-3.1-flash-image-preview입니다.
  • google/gemini-3-pro-image-preview도 지원합니다
  • 생성: 요청당 최대 4개 이미지
  • 편집 모드: 활성화됨, 최대 5개 입력 이미지
  • 기하 제어: size, aspectRatio, resolution
Google을 기본 이미지 provider로 사용하려면: 
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "google/gemini-3.1-flash-image-preview",
      },
    },
  },
}
공통 도구 매개변수, provider 선택, 장애 조치 동작은 Image Generation을 참조하세요.

​
비디오 생성

번들 google Plugin은 공유 video_generate 도구를 통해 비디오 생성도 등록합니다.
  • 기본 비디오 모델: google/veo-3.1-fast-generate-preview
  • 모드: 텍스트-비디오, 이미지-비디오, 단일 비디오 참조 흐름
  • aspectRatio, resolution, audio 지원
  • 현재 길이 제한: 4~8초
Google을 기본 비디오 provider로 사용하려면: 
{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "google/veo-3.1-fast-generate-preview",
      },
    },
  },
}
공통 도구 매개변수, provider 선택, 장애 조치 동작은 Video Generation을 참조하세요.

​
음악 생성

번들 google Plugin은 공유 music_generate 도구를 통해 음악 생성도 등록합니다.
  • 기본 음악 모델: google/lyria-3-clip-preview
  • google/lyria-3-pro-preview도 지원합니다
  • 프롬프트 제어: lyrics 및 instrumental
  • 출력 형식: 기본값은 mp3, google/lyria-3-pro-preview에서는 wav도 지원
  • 참조 입력: 최대 10개 이미지
  • 세션 기반 실행은 action: "status"를 포함한 공유 작업/상태 흐름을 통해 분리되어 처리됩니다
Google을 기본 음악 provider로 사용하려면: 
{
  agents: {
    defaults: {
      musicGenerationModel: {
        primary: "google/lyria-3-clip-preview",
      },
    },
  },
}
공통 도구 매개변수, provider 선택, 장애 조치 동작은 Music Generation을 참조하세요.

​
고급 구성

직접 Gemini API 실행(api: "google-generative-ai")의 경우, OpenClaw는 구성된 cachedContent 핸들을 Gemini 요청에 그대로 전달합니다.
  • 모델별 또는 전역 params에 cachedContent 또는 레거시 cached_content를 사용해 구성할 수 있습니다
  • 둘 다 있으면 cachedContent가 우선합니다
  • 예시 값: cachedContents/prebuilt-context
  • Gemini 캐시 적중 사용량은 업스트림 cachedContentTokenCount에서 OpenClaw cacheRead로 정규화됩니다
{
  agents: {
    defaults: {
      models: {
        "google/gemini-2.5-pro": {
          params: {
            cachedContent: "cachedContents/prebuilt-context",
          },
        },
      },
    },
  },
}
google-gemini-cli OAuth provider를 사용할 때 OpenClaw는 CLI JSON 출력을 다음과 같이 정규화합니다:
  • 답글 텍스트는 CLI JSON response 필드에서 가져옵니다.
  • CLI가 usage를 비워 둘 경우 사용량은 stats로 대체됩니다.
  • stats.cached는 OpenClaw cacheRead로 정규화됩니다.
  • stats.input이 없으면 OpenClaw는 stats.input_tokens - stats.cached에서 입력 토큰 수를 계산합니다.
Gateway가 데몬(launchd/systemd)으로 실행되는 경우 GEMINI_API_KEY가 해당 프로세스에서 사용 가능해야 합니다(예: ~/.openclaw/.env 또는 env.shellEnv에서).

​
관련

모델 선택

provider, 모델 참조 및 장애 조치 동작 선택하기.

이미지 생성

공통 이미지 도구 매개변수 및 provider 선택.

비디오 생성

공통 비디오 도구 매개변수 및 provider 선택.

음악 생성

공통 음악 도구 매개변수 및 provider 선택.