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을 사용하여 48 kHz 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 기반의 실시간 음성 제공자를 등록합니다.

Voice Call 실시간 구성 예시:

{  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 Talk가 사용하는 것과 동일한 형태의 제한된 Live API 토큰을 발급하고, 브라우저 WebSocket 엔드포인트를 열고, 초기 설정 페이로드를 전송한 후 setupComplete을 기다립니다.

고급 구성

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

관련 항목