Google(Gemini)

Google Plugin은 Google AI Studio를 통해 Gemini 모델에 액세스할 수 있게 하며, 이미지 생성, 미디어 이해(이미지/오디오/동영상), 텍스트 음성 변환, Gemini Grounding을 통한 웹 검색도 제공합니다.

• 제공자: google
• 인증: GEMINI_API_KEY 또는 GOOGLE_API_KEY
• API: Google Gemini API
• 런타임 옵션: agentRuntime.id: "google-gemini-cli"는 모델 참조를 표준 google/* 형식으로 유지하면서 Gemini CLI OAuth를 재사용합니다.

시작하기

선호하는 인증 방법을 선택하고 설정 단계를 따르세요.

openclaw onboard --auth-choice gemini-api-key

openclaw onboard --non-interactive \  --mode local \  --auth-choice gemini-api-key \  --gemini-api-key "$GEMINI_API_KEY"

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

openclaw models list --provider google

# Homebrewbrew install gemini-cli # 또는 npmnpm install -g @google/gemini-cli

openclaw models auth login --provider google-gemini-cli --set-default

openclaw models list --provider google

기능

웹 검색

번들 gemini 웹 검색 제공자는 Gemini Google Search Grounding을 사용합니다. plugins.entries.google.config.webSearch에서 전용 검색 키를 구성하거나, GEMINI_API_KEY 다음으로 models.providers.google.apiKey를 재사용하도록 할 수 있습니다.

{  plugins: {    entries: {      google: {        config: {          webSearch: {            apiKey: "AIza...", // GEMINI_API_KEY 또는 models.providers.google.apiKey가 설정되어 있으면 선택 사항            baseUrl: "https://generativelanguage.googleapis.com/v1beta", // models.providers.google.baseUrl로 대체            model: "gemini-2.5-flash",          },        },      },    },  },}

자격 증명의 우선순위는 전용 webSearch.apiKey, GEMINI_API_KEY, models.providers.google.apiKey 순입니다. webSearch.baseUrl은 선택 사항이며 운영자 프록시 또는 호환되는 Gemini API 엔드포인트를 위해 제공됩니다. 생략하면 Gemini 웹 검색은 models.providers.google.baseUrl을 재사용합니다. 제공자별 도구 동작은 Gemini 검색을 참조하세요.

이미지 생성

번들 google 이미지 생성 제공자의 기본값은 google/gemini-3.1-flash-image-preview입니다.

• google/gemini-3-pro-image-preview도 지원
• 생성: 요청당 최대 4개 이미지
• 편집 모드: 활성화됨, 입력 이미지 최대 5개
• 크기 제어: size, aspectRatio, resolution

Google을 기본 이미지 제공자로 사용하려면 다음과 같이 설정합니다.

{  agents: {    defaults: {      imageGenerationModel: {        primary: "google/gemini-3.1-flash-image-preview",      },    },  },}

동영상 생성

번들 google Plugin은 공통 video_generate 도구를 통한 동영상 생성도 등록합니다.

• 기본 동영상 모델: google/veo-3.1-fast-generate-preview
• 모드: 텍스트-동영상, 이미지-동영상 및 단일 동영상 참조 흐름
• aspectRatio(16:9, 9:16) 및 resolution(720P, 1080P) 지원. 현재 Veo는 오디오 출력을 지원하지 않음
• 지원되는 길이: 4초, 6초 또는 8초(다른 값은 가장 가까운 허용 값으로 조정됨)

Google을 기본 동영상 제공자로 사용하려면 다음과 같이 설정합니다.

{  agents: {    defaults: {      videoGenerationModel: {        primary: "google/veo-3.1-fast-generate-preview",      },    },  },}

음악 생성

번들 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을 기본 음악 제공자로 사용하려면 다음과 같이 설정합니다.

{  agents: {    defaults: {      musicGenerationModel: {        primary: "google/lyria-3-clip-preview",      },    },  },}

텍스트 음성 변환

번들 google 음성 제공자는 gemini-3.1-flash-tts-preview를 사용하는 Gemini API TTS 경로를 사용합니다.

• 기본 음성: Kore
• 인증: messages.tts.providers.google.apiKey, models.providers.google.apiKey, GEMINI_API_KEY 또는 GOOGLE_API_KEY
• 출력: 일반 TTS 첨부 파일에는 WAV, 음성 메모 대상에는 Opus, Talk/전화 통신에는 PCM
• 음성 메모 출력: Google PCM을 WAV로 래핑하고 ffmpeg를 사용해 48kHz Opus로 트랜스코딩

Google의 배치 Gemini TTS 경로는 완료된 generateContent 응답에서 생성된 오디오를 반환합니다. 지연 시간이 가장 짧은 음성 대화가 필요하면 배치 TTS 대신 Gemini Live API 기반의 Google 실시간 음성 제공자를 사용하세요.

Google을 기본 TTS 제공자로 사용하려면 다음과 같이 설정합니다.

{  messages: {    tts: {      auto: "always",      provider: "google",      providers: {        google: {          model: "gemini-3.1-flash-tts-preview",          speakerVoice: "Kore",          audioProfile: "차분한 어조로 전문적으로 말합니다.",        },      },    },  },}

Gemini API TTS는 스타일 제어에 자연어 프롬프트를 사용합니다. 음성으로 읽을 텍스트 앞에 재사용 가능한 스타일 프롬프트를 추가하려면 audioProfile을 설정하세요. 프롬프트 텍스트에서 이름이 지정된 화자를 참조할 때는 speakerName을 설정하세요.

Gemini API TTS는 텍스트에서 [whispers] 또는 [laughs]와 같은 표현력이 있는 대괄호 오디오 태그도 허용합니다. 태그를 TTS에는 전송하면서 표시되는 채팅 응답에서는 제외하려면 [[tts:text]]...[[/tts:text]] 블록 안에 넣으세요.

여기에 깔끔한 응답 텍스트가 있습니다. [[tts:text]][whispers] 여기에 음성으로 읽을 버전이 있습니다.[[/tts:text]]

실시간 음성

번들 google Plugin은 Voice Call 및 Google Meet와 같은 백엔드 오디오 브리지를 위해 Gemini Live API 기반의 실시간 음성 제공자를 등록합니다.

음성 통화 실시간 구성 예시:

{  plugins: {    entries: {      "voice-call": {        enabled: true,        config: {          realtime: {            enabled: true,            provider: "google",            providers: {              google: {                model: "gemini-3.1-flash-live-preview",                speakerVoice: "Kore",                activityHandling: "start-of-activity-interrupts",                turnCoverage: "audio-activity-and-all-video",              },            },          },        },      },    },  },}

유지관리자가 라이브 검증을 수행하려면 OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts를 실행하세요. 이 스모크 테스트는 OpenAI 백엔드/WebRTC 경로도 다룹니다. Google 구간에서는 Control UI 대화가 사용하는 것과 동일한 형태의 제한된 Live API 토큰을 발급하고, 브라우저 WebSocket 엔드포인트를 열고, 초기 설정 페이로드를 전송한 다음 setupComplete를 기다립니다.

고급 구성

{  agents: {    defaults: {      models: {        "google/gemini-2.5-pro": {          params: {            cachedContent: "cachedContents/prebuilt-context",          },        },      },    },  },}

관련 항목