OpenClaw에서 Google Gemini 모델 연동 가이드

서문

Google Gemini는 Google이 출시한 차세대 멀티모달 AI 모델로, 강력한 텍스트, 이미지, 오디오, 비디오 이해 능력을 갖추고 있습니다. OpenClaw는 Gemini 시리즈 모델을 완벽하게 지원하며, Google은 매우 넉넉한 무료 할당량을 제공하여 개인 사용자와 소규모 팀에 매우 적합합니다. 본 가이드에서는 Gemini 모델 연동 방법을 상세히 안내합니다.

사전 준비

조건	설명
OpenClaw 설치 및 정상 실행	`openclaw doctor` 검사 통과
Google 계정	Google AI Studio 로그인용
네트워크 환경	Google 서비스에 접속 가능해야 함

1단계: Gemini API Key 발급

1.1 Google AI Studio를 통한 발급 (권장)

가장 간단한 발급 방법으로, 개인 개발자에게 적합합니다:

aistudio.google.com에 접속합니다
Google 계정으로 로그인합니다
왼쪽 메뉴에서 Get API key를 클릭합니다
Create API key를 클릭합니다
기존 Google Cloud 프로젝트를 선택하거나 새 프로젝트를 생성합니다
생성된 API Key를 복사합니다

API Key 형식 예시:

AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

1.2 사용 가능 지역 확인

Gemini API는 일부 지역에서 사용이 불가능할 수 있습니다. 2026년 기준으로 다음 지역이 지원됩니다:

미국, 캐나다
유럽 대부분 국가
일본, 한국, 싱가포르, 인도
호주

해당 지역이 지원되지 않는 경우 Vertex AI 방안을 고려해 볼 수 있습니다 (후술 참조).

2단계: OpenClaw 설정

2.1 기본 설정

OpenClaw 설정 파일을 편집합니다:

nano ~/.config/openclaw/openclaw.json5

Gemini 모델 설정을 추가합니다:

{
  models: {
    gemini: {
      provider: "google",
      apiKey: "AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      defaultModel: "gemini-2.5-pro",
    }
  }
}

2.2 환경 변수로 키 저장

# ~/.bashrc 또는 ~/.zshrc에 추가
export GOOGLE_AI_API_KEY="AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

설정 파일에서 환경 변수를 참조하도록 변경합니다:

{
  models: {
    gemini: {
      provider: "google",
      apiKey: "${GOOGLE_AI_API_KEY}",
      defaultModel: "gemini-2.5-pro",
    }
  }
}

2.3 서비스 재시작

openclaw restart
openclaw doctor

✓ Google Gemini connection OK가 표시되면 설정이 완료된 것입니다.

3단계: Gemini 모델 선택

Google은 현재 각각 다른 특성을 가진 여러 Gemini 모델을 제공합니다:

모델	컨텍스트 윈도우	특징	추천 사용 사례
gemini-2.5-pro	1M tokens	최강 추론 능력, 심층 사고	복잡한 분석, 코드 생성, 장문 처리
gemini-2.5-flash	1M tokens	빠른 응답, 높은 가성비	일상 대화, 빠른 질의응답
gemini-2.0-flash	1M tokens	이전 세대 고속 모델	지연에 민감한 사용 사례
gemini-2.0-flash-lite	1M tokens	가장 경량화된 모델	간단한 작업, 고빈도 처리

3.1 권장 설정 방안

대부분의 사용자에게는 다음 조합을 권장합니다:

{
  models: {
    "gemini-main": {
      provider: "google",
      apiKey: "${GOOGLE_AI_API_KEY}",
      defaultModel: "gemini-2.5-pro",
      parameters: {
        temperature: 0.7,
        maxTokens: 8192,
      }
    },
    "gemini-fast": {
      provider: "google",
      apiKey: "${GOOGLE_AI_API_KEY}",
      defaultModel: "gemini-2.5-flash",
      parameters: {
        temperature: 0.7,
        maxTokens: 4096,
      }
    }
  }
}

4단계: 무료 할당량 상세 안내

Google AI Studio에서 제공하는 무료 할당량은 매우 넉넉합니다:

모델	무료 RPM (분당 요청 수)	무료 TPM (분당 토큰)	무료 RPD (일일 요청 수)
gemini-2.5-pro	5	250,000	25
gemini-2.5-flash	15	1,000,000	500
gemini-2.0-flash	15	1,000,000	1,500
gemini-2.0-flash-lite	30	1,000,000	3,000

개인 사용자의 경우 gemini-2.5-flash의 무료 할당량으로 기본적으로 충분합니다. 무료 할당량을 초과하는 경우 Google Cloud Console에서 유료 플랜을 활성화할 수 있습니다.

4.1 무료 할당량을 최대한 활용하는 팁

{
  models: {
    gemini: {
      provider: "google",
      apiKey: "${GOOGLE_AI_API_KEY}",
      defaultModel: "gemini-2.5-flash",  // 기본으로 flash 사용, 무료 할당량이 더 많음
      parameters: {
        maxTokens: 2048,                  // 출력 길이 제한으로 토큰 절약
      }
    }
  },
  rateLimit: {
    gemini: {
      maxRequestsPerMinute: 14,           // 여유를 두어 제한 트리거 방지
      maxRequestsPerDay: 480,
    }
  }
}

5단계: Vertex AI 방안

엔터프라이즈급 서비스가 필요하거나 해당 지역에서 AI Studio를 지원하지 않는 경우, Google Cloud의 Vertex AI를 사용할 수 있습니다:

5.1 Vertex AI 활성화

Google Cloud Console에 로그인합니다
프로젝트를 생성하거나 선택합니다
Vertex AI API를 활성화합니다
서비스 계정을 생성하고 JSON 키 파일을 다운로드합니다

5.2 OpenClaw에서 Vertex AI 사용 설정

{
  models: {
    "gemini-vertex": {
      provider: "google-vertex",
      serviceAccountKeyFile: "/path/to/service-account-key.json",
      projectId: "your-gcp-project-id",
      region: "us-central1",            // 가장 가까운 리전 선택
      defaultModel: "gemini-2.5-pro",
      parameters: {
        temperature: 0.7,
        maxTokens: 8192,
      }
    }
  }
}

5.3 Vertex AI와 AI Studio 비교

비교 항목	AI Studio	Vertex AI
적합 대상	개인, 소규모 팀	기업, 프로덕션 환경
인증 방식	API Key	서비스 계정
무료 할당량	있음	제한된 무료 체험
SLA 보장	없음	있음
데이터 처리 위치	보장 없음	리전 지정 가능
과금 방식	사용량 기반	사용량 기반, 예약 할인 지원

6단계: 멀티모달 기능 설정

Gemini의 가장 큰 강점은 네이티브 멀티모달 지원입니다. 채팅 채널을 통해 이미지, PDF 등의 콘텐츠를 보내면 Gemini가 이해하고 응답할 수 있습니다.

6.1 이미지 이해 활성화

{
  models: {
    gemini: {
      provider: "google",
      apiKey: "${GOOGLE_AI_API_KEY}",
      defaultModel: "gemini-2.5-flash",
      capabilities: {
        vision: true,        // 이미지 이해 활성화
        pdf: true,           // PDF 분석 활성화
        audio: true,         // 오디오 이해 활성화
      }
    }
  }
}

6.2 지원 파일 형식

파일 유형	지원 형식	설명
이미지	PNG, JPEG, WebP, GIF	여러 이미지 동시 입력 지원
문서	PDF	PDF 콘텐츠 추출 및 이해 가능
오디오	MP3, WAV, FLAC	음성 인식 및 이해 지원
비디오	MP4, WEBM	비디오 콘텐츠 이해 가능 (일부 모델)

7단계: 일반적인 문제 해결

API Key 무효

Error: API key not valid. Please pass a valid API key.

API Key가 올바르게 복사되었는지, AIza로 시작하는지 확인하십시오. 여전히 오류가 발생하면 AI Studio에서 다시 생성해 보십시오.

지역 제한

Error: User location is not supported for the API use.

해당 지역에서 Gemini API를 지원하지 않을 수 있습니다. 해결 방안:

Vertex AI 방안 사용
OpenRouter를 통해 간접적으로 Gemini 호출 (OpenRouter 가이드 참조)

무료 할당량 초과

Error: 429 Resource has been exhausted

해결 방법:

gemini-2.0-flash-lite로 전환, 무료 할당량이 더 많음
Google Cloud 유료 플랜 활성화
OpenClaw에서 속도 제한을 설정하여 빈번한 트리거 방지

응답 잘림

응답이 자주 잘리는 경우 maxTokens 설정을 확인하십시오:

parameters: {
  maxTokens: 8192,  // 출력 제한 확대
}

요약

Gemini 모델은 OpenClaw 생태계에서 가성비가 매우 높은 선택입니다. 넉넉한 무료 할당량과 강력한 멀티모달 기능을 활용하면, 개인 사용자도 비용 부담 없이 기능이 풍부한 AI 어시스턴트를 운영할 수 있습니다. 일상적으로는 gemini-2.5-flash를 사용하여 속도와 품질의 균형을 맞추고, 복잡한 작업에는 gemini-2.5-pro로 전환하는 것을 권장합니다. 팀에서 엔터프라이즈급 요구사항이 있다면 Vertex AI 방안을 진지하게 고려해 볼 가치가 있습니다.