Google (Gemini)

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

• 제공자: google
• 인증: GEMINI_API_KEY 또는 GOOGLE_API_KEY
• API: Google Gemini API
• 런타임 옵션: agents.defaults.agentRuntime.id: "google-gemini-cli" Gemini CLI OAuth를 재사용하면서 모델 참조는 google/*로 정규화된 상태를 유지합니다.

# 시작하기

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

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

# Homebrew
brew install gemini-cli

# or npm
npm 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...", // 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을 재사용합니다. 제공자별 도구 동작은 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, resolution, audio 지원
• 현재 길이 제한: 4초에서 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",
          voiceName: "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 기반 실시간 음성 제공자를 등록합니다.

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",
                voice: "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를 실행하세요. Google 구간은 Control UI Talk에서 사용하는 것과 동일한 제한된 Live API 토큰 형태를 발급하고, 브라우저 WebSocket 엔드포인트를 열고, 초기 설정 페이로드를 보낸 뒤 setupComplete를 기다립니다.

# 고급 구성

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

# 관련 항목