Google (Gemini)

Google Plugin은 Google AI Studio를 통해 Gemini 모델에 접근할 수 있게 해 주며, 이미지 생성, 미디어 이해(이미지/오디오/비디오), 텍스트 음성 변환, 그리고 Gemini Grounding을 통한 웹 검색을 제공합니다.

• Provider: google
• Auth: GEMINI_API_KEY 또는 GOOGLE_API_KEY
• API: Google Gemini API
• 런타임 옵션: provider/model 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 # or npmnpm install -g @google/gemini-cli

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

openclaw models list --provider google

기능

웹 검색

번들된 gemini 웹 검색 provider는 Gemini Google Search grounding을 사용합니다. plugins.entries.google.config.webSearch 아래에 전용 검색 키를 구성하거나, GEMINI_API_KEY 이후 models.providers.google.apiKey를 재사용하게 할 수 있습니다.

{  plugins: {    entries: {      google: {        config: {          webSearch: {            apiKey: "AIza...", // optional if GEMINI_API_KEY or models.providers.google.apiKey is set            baseUrl: "https://generativelanguage.googleapis.com/v1beta", // falls back to 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을 재사용합니다. provider별 도구 동작은 Gemini 검색을 참조하세요.

이미지 생성

번들된 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",      },    },  },}

비디오 생성

번들된 google Plugin은 공유 video_generate 도구를 통해 비디오 생성도 등록합니다.

• 기본 비디오 모델: google/veo-3.1-fast-generate-preview
• 모드: 텍스트-비디오, 이미지-비디오, 단일 비디오 참조 흐름
• aspectRatio(16:9, 9:16) 및 resolution(720P, 1080P) 지원. 오디오 출력은 현재 Veo에서 지원되지 않습니다.
• 지원 지속 시간: 4, 6 또는 8초(다른 값은 가장 가까운 허용 값으로 맞춰짐)

Google을 기본 비디오 provider로 사용하려면 다음과 같이 설정합니다.

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

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

텍스트 음성 변환

번들된 google 음성 provider는 gemini-3.1-flash-tts-preview와 함께 Gemini API TTS 경로를 사용합니다.

• 기본 음성: Kore
• Auth: messages.tts.providers.google.apiKey, models.providers.google.apiKey, GEMINI_API_KEY 또는 GOOGLE_API_KEY
• 출력: 일반 TTS 첨부 파일은 WAV, 음성 메모 대상은 Opus, Talk/전화는 PCM
• 음성 메모 출력: Google PCM은 WAV로 래핑되고 ffmpeg로 48 kHz Opus로 트랜스코딩됩니다.

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

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

{  messages: {    tts: {      auto: "always",      provider: "google",      providers: {        google: {          model: "gemini-3.1-flash-tts-preview",          speakerVoice: "Kore",          audioProfile: "Speak professionally with a calm tone.",        },      },    },  },}

Gemini API TTS는 스타일 제어에 자연어 프롬프트를 사용합니다. 말할 텍스트 앞에 재사용 가능한 스타일 프롬프트를 붙이려면 audioProfile을 설정하세요. 프롬프트 텍스트가 이름 있는 화자를 참조할 때는 speakerName을 설정하세요.

Gemini API TTS는 텍스트에서 [whispers] 또는 [laughs] 같은 표현적인 대괄호 오디오 태그도 허용합니다. 태그를 보이는 채팅 답장에는 표시하지 않고 TTS로 보내려면 [[tts:text]]...[[/tts:text]] 블록 안에 넣으세요.

Here is the clean reply text. [[tts:text]][whispers] Here is the spoken version.[[/tts:text]]

실시간 음성

번들된 google Plugin은 Voice Call 및 Google Meet 같은 백엔드 오디오 브리지용 Gemini Live API 기반 실시간 음성 provider를 등록합니다.

Voice Call 실시간 구성 예:

{  plugins: {    entries: {      "voice-call": {        enabled: true,        config: {          realtime: {            enabled: true,            provider: "google",            providers: {              google: {                model: "gemini-2.5-flash-native-audio-preview-12-2025",                speakerVoice: "Kore",                activityHandling: "start-of-activity-interrupts",                turnCoverage: "only-activity",              },            },          },        },      },    },  },}

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

고급 구성

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

관련 항목