Google (Gemini) - OpenClaw

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를 재사용합니다.

시작하기

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

API 키
Gemini CLI (OAuth)

가장 적합한 경우: Google AI Studio를 통한 표준 Gemini API 접근.

온보딩 실행

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

환경 변수 GEMINI_API_KEY와 GOOGLE_API_KEY를 모두 사용할 수 있습니다. 이미 구성해 둔 것을 사용하세요.

가장 적합한 경우: 별도의 API 키 대신 PKCE OAuth를 통해 기존 Gemini CLI 로그인을 재사용.

google-gemini-cli provider는 비공식 통합입니다. 일부 사용자는 이 방식으로 OAuth를 사용할 때 계정 제한이 발생한다고 보고합니다. 본인 책임하에 사용하세요.

Gemini CLI 설치

로컬 gemini 명령은 PATH에서 사용할 수 있어야 합니다.

# Homebrew
brew install gemini-cli

# or npm
npm install -g @google/gemini-cli

OpenClaw는 일반적인 Windows/npm 레이아웃을 포함해 Homebrew 설치와 전역 npm 설치를 모두 지원합니다.

OAuth로 로그인

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

모델 사용 가능 여부 확인

openclaw models list --provider google

기본 모델: google/gemini-3.1-pro-preview
런타임: google-gemini-cli
별칭: gemini-cli

Gemini 3.1 Pro의 Gemini API 모델 ID는 gemini-3.1-pro-preview입니다. OpenClaw는 편의 별칭으로 더 짧은 google/gemini-3.1-pro를 허용하며, provider 호출 전에 이를 정규화합니다.환경 변수:

OPENCLAW_GEMINI_OAUTH_CLIENT_ID
OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET

(또는 GEMINI_CLI_* 변형.)

로그인 후 Gemini CLI OAuth 요청이 실패하면 Gateway 호스트에 GOOGLE_CLOUD_PROJECT 또는 GOOGLE_CLOUD_PROJECT_ID를 설정하고 다시 시도하세요.

브라우저 흐름이 시작되기 전에 로그인이 실패하면 로컬 gemini 명령이 설치되어 있고 PATH에 있는지 확인하세요.

google-gemini-cli/* 모델 참조는 레거시 호환성 별칭입니다. 새 구성에서는 로컬 Gemini CLI 실행을 원할 때 google/* 모델 참조와 google-gemini-cli 런타임을 함께 사용해야 합니다.

기능

기능	지원 여부
채팅 완성	예
이미지 생성	예
음악 생성	예
텍스트 음성 변환	예
실시간 음성	예(Google Live API)
이미지 이해	예
오디오 전사	예
비디오 이해	예
웹 검색(Grounding)	예
사고/추론	예(Gemini 2.5+ / Gemini 3+)
Gemma 4 모델	예

웹 검색

번들된 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 검색을 참조하세요.

Gemini 3 모델은 thinkingBudget 대신 thinkingLevel을 사용합니다. OpenClaw는 Gemini 3, Gemini 3.1, 그리고 gemini-*-latest 별칭 추론 제어를 thinkingLevel에 매핑하여 기본/저지연 실행에서 비활성화된 thinkingBudget 값을 보내지 않도록 합니다./think adaptive는 고정 OpenClaw 수준을 선택하는 대신 Google의 동적 사고 의미 체계를 유지합니다. Gemini 3 및 Gemini 3.1은 고정 thinkingLevel을 생략하여 Google이 수준을 선택할 수 있게 합니다. Gemini 2.5는 Google의 동적 sentinel thinkingBudget: -1을 보냅니다.Gemma 4 모델(예: gemma-4-26b-a4b-it)은 사고 모드를 지원합니다. OpenClaw는 Gemma 4에 대해 thinkingBudget을 지원되는 Google thinkingLevel로 다시 작성합니다. 사고를 off로 설정하면 MINIMAL로 매핑하지 않고 사고 비활성화 상태를 유지합니다.

이미지 생성

번들된 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 선택, 장애 조치 동작은 이미지 생성을 참조하세요.

비디오 생성

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

공유 도구 매개변수, provider 선택, 장애 조치 동작은 비디오 생성을 참조하세요.

음악 생성

번들된 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 선택, 장애 조치 동작은 음악 생성을 참조하세요.

텍스트 음성 변환

번들된 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]]

Gemini API로 제한된 Google Cloud Console API 키는 이 provider에 유효합니다. 이는 별도의 Cloud Text-to-Speech API 경로가 아닙니다.

실시간 음성

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

설정	구성 경로	기본값
모델	`plugins.entries.voice-call.config.realtime.providers.google.model`	`gemini-2.5-flash-native-audio-preview-12-2025`
음성	`...google.voice`	`Kore`
온도	`...google.temperature`	(설정되지 않음)
VAD 시작 민감도	`...google.startSensitivity`	(설정되지 않음)
VAD 종료 민감도	`...google.endSensitivity`	(설정되지 않음)
무음 지속 시간	`...google.silenceDurationMs`	(설정되지 않음)
활동 처리	`...google.activityHandling`	Google 기본값, `start-of-activity-interrupts`
턴 적용 범위	`...google.turnCoverage`	Google 기본값, `only-activity`
자동 VAD 비활성화	`...google.automaticActivityDetectionDisabled`	`false`
세션 재개	`...google.sessionResumption`	`true`
컨텍스트 압축	`...google.contextWindowCompression`	`true`
API 키	`...google.apiKey`	`models.providers.google.apiKey`, `GEMINI_API_KEY` 또는 `GOOGLE_API_KEY`로 폴백합니다

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",
              },
            },
          },
        },
      },
    },
  },
}

Google Live API는 WebSocket을 통해 양방향 오디오와 함수 호출을 사용합니다. OpenClaw는 전화/Meet 브리지 오디오를 Gemini의 PCM Live API 스트림에 맞게 조정하고 도구 호출은 공유 실시간 음성 계약에 유지합니다. 샘플링 변경이 필요한 경우가 아니라면 temperature를 설정하지 않은 상태로 두세요. Google Live는 temperature: 0에서 오디오 없이 transcript를 반환할 수 있으므로 OpenClaw는 양수가 아닌 값을 생략합니다. Gemini API transcription은 languageCodes 없이 활성화됩니다. 현재 Google SDK는 이 API 경로에서 언어 코드 힌트를 거부합니다.

Control UI Talk는 제한된 일회용 토큰으로 Google Live 브라우저 세션을 지원합니다. 백엔드 전용 실시간 음성 공급자도 일반 Gateway 릴레이 전송을 통해 실행할 수 있으며, 이 방식은 공급자 자격 증명을 Gateway에 유지합니다.

관리자 라이브 검증의 경우 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를 기다립니다.

고급 구성

Direct Gemini cache reuse

직접 Gemini API 실행(api: "google-generative-ai")의 경우 OpenClaw는 구성된 cachedContent 핸들을 Gemini 요청에 전달합니다.

cachedContent 또는 레거시 cached_content로 모델별 또는 전역 매개변수를 구성합니다
둘 다 있으면 cachedContent가 우선합니다
예시 값: cachedContents/prebuilt-context
Gemini 캐시 적중 사용량은 업스트림 cachedContentTokenCount에서 OpenClaw cacheRead로 정규화됩니다

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

Gemini CLI usage notes

google-gemini-cli OAuth 공급자를 사용할 때 OpenClaw는 기본적으로 Gemini CLI stream-json 출력을 사용하고 최종 stats 페이로드에서 사용량을 정규화합니다. 레거시 --output-format json 재정의는 여전히 JSON 파서를 사용합니다.

스트리밍된 응답 텍스트는 어시스턴트 message 이벤트에서 가져옵니다.
레거시 JSON 출력의 경우 응답 텍스트는 CLI JSON response 필드에서 가져옵니다.
CLI가 usage를 비워 두면 사용량은 stats로 폴백합니다.
stats.cached는 OpenClaw cacheRead로 정규화됩니다.
stats.input이 없으면 OpenClaw는 stats.input_tokens - stats.cached에서 입력 토큰을 파생합니다.

Environment and daemon setup

Gateway가 데몬(launchd/systemd)으로 실행되는 경우 GEMINI_API_KEY가 해당 프로세스에서 사용할 수 있는지 확인하세요(예: ~/.openclaw/.env 또는 env.shellEnv를 통해).

Model selection

공급자, 모델 참조, 장애 조치 동작 선택.

Image generation

공유 이미지 도구 매개변수 및 공급자 선택.

Video generation

공유 비디오 도구 매개변수 및 공급자 선택.

Music generation

공유 음악 도구 매개변수 및 공급자 선택.

​시작하기

​기능

​웹 검색

​이미지 생성

​비디오 생성

​음악 생성

​텍스트 음성 변환

​실시간 음성

​고급 구성

​관련 항목

Model selection

Image generation

Video generation

Music generation

시작하기

기능

웹 검색

이미지 생성

비디오 생성

음악 생성

텍스트 음성 변환

실시간 음성

고급 구성

관련 항목