OpenClaw에 Google Gemini 연결하기

개발을 하다 보면 긴 문서를 분석하거나 방대한 대화 기록을 유지해야 할 때가 있죠. 하지만 토큰 비용이 걱정되어 마음껏 쓰지 못하고 주춤했던 경험, 다들 한 번쯤은 있을 거예요. 특히 고성능 모델을 쓰다 보면 순식간에 불어나는 비용 때문에 개발 의욕이 꺾이기도 합니다.

Google Gemini는 이런 고민을 해결해 줄 아주 좋은 선택지예요. Gemini의 무료 티어는 정말 파격적이거든요. Claude나 GPT는 토큰마다 비용을 받지만, Gemini는 100만 토큰의 컨텍스트 창과 넉넉한 무료 혜택을 제공합니다. 긴 문서를 처리하거나 방대한 대화 흐름을 유지해야 한다면 Gemini가 정답이에요.

OpenClaw에서 Gemini를 어떻게 설정하는지 바로 알려드릴게요.

---

Why Gemini?

기능	Gemini	Claude	GPT-4
무료 티어	✅ 제공	❌ 미제공	❌ 미제공
컨텍스트 창	1M tokens	200K tokens	128K tokens
멀티모달	✅ 이미지, 오디오, 비디오	✅ 이미지	✅ 이미지
속도	빠름	보통	보통

---

필요한 것

시작하기 전에 다음 사항들이 준비되어 있는지 확인해 주세요.

• Google 계정
• 설치된 OpenClaw

---

Quick Start (5분 완성)

Step 1: API Key 받기

1. Google AI Studio에 접속하세요.
2. Google 계정으로 로그인합니다.
3. “Get API Key” → “Create API Key”를 클릭하세요.
4. 발급된 API Key를 복사해 둡니다.

Step 2: OpenClaw 설정하기

방법 A: 환경 변수 사용

export GEMINI_API_KEY="여러분의-API-키를-입력하세요"

방법 B: CLI 설정 사용

openclaw config set models.providers.gemini.apiKey "여러분의-API-키를-입력하세요"

Step 3: Gemini를 기본 모델로 설정하기

OpenClaw 설정 파일을 다음과 같이 수정하세요.

{
  agents: {
    defaults: {
      model: { primary: "gemini/gemini-2.5-flash" }
    }
  }
}

이제 모든 준비가 끝났습니다. 바로 Gemini를 사용할 수 있어요.

---

OAuth 인증 (대체 방법)

API Key를 직접 관리하는 대신 Google 계정을 통해 더 안전하게 인증하고 싶다면 다음 방법을 사용해 보세요.

방법 1: Onboarding Wizard 이용

1. openclaw onboard 명령어를 실행하세요.
2. AI Provider로 “Google”을 선택합니다.
3. “OAuth Authentication”을 선택하세요.
4. 브라우저에서 Google 로그인 과정을 완료합니다.
5. OpenClaw가 인증 토큰을 안전하게 저장합니다.

방법 2: CLI Plugin 인증

이미 OpenClaw를 설치했다면 Gemini CLI 인증 플러그인을 활성화할 수 있습니다.

# Gemini CLI 인증 플러그인 활성화
openclaw plugins enable google-gemini-cli-auth

# 인증 및 기본 Provider로 설정
openclaw models auth login --provider google-gemini-cli --set-default

명령어를 입력하면 Google OAuth를 위한 브라우저 창이 열립니다. 인증이 완료되면 API Key 없이도 Gemini를 쓸 수 있어요.

참고: OAuth는 개인적인 용도로 쓰기에 좋습니다. 자동화나 서버 배포 환경에서는 API Key를 사용하세요.

---

사용 가능한 Gemini 모델

모델	용도	컨텍스트 창
gemini-2.5-flash	빠른 응답 속도	1M tokens
gemini-2.5-pro	복잡한 추론	1M tokens
gemini-2.0-flash	균형 잡힌 성능	128K tokens

모델 선택 예시

{
  agents: {
    defaults: {
      model: {
        primary: "gemini/gemini-2.5-flash",
        fallback: ["gemini/gemini-2.0-flash"]
      }
    }
  }
}

---

Gemini 무료 티어 이해하기

Google의 무료 티어 구성은 다음과 같습니다.

• 분당 60회 요청 (Flash 모델)
• 분당 2회 요청 (Pro 모델)
• 100만 토큰 컨텍스트 창

대부분의 개인적인 용도라면 무료 티어만으로도 충분합니다.

Rate Limits (속도 제한)

제한에 걸린다면 다음 방법을 고려해 보세요.

• 제한 수치가 더 높은 Flash 모델로 변경하기
• 요청 사이에 지연 시간 추가하기
• Gemini API 유료 플랜으로 업그레이드하기

---

Advanced Configuration

전체 Provider 설정

{
  models: {
    providers: {
      gemini: {
        apiKey: "여러분의-API-키",
        models: [
          {
            id: "gemini-2.5-flash",
            name: "Gemini 2.5 Flash",
            reasoning: false,
            input: ["text", "image"],
            contextWindow: 1000000,
            maxTokens: 8192
          }
        ]
      }
    }
  }
}

다른 Provider와 함께 사용하기

Gemini를 다른 모델과 섞어서 사용할 수도 있습니다.

{
  agents: {
    defaults: {
      model: {
        primary: "gemini/gemini-2.5-flash",  // 빠르고 무료
        fallback: ["anthropic/claude-sonnet-4"] // 복잡한 작업용
      }
    }
  }
}

---

문제 해결

”API key not valid”

API Key를 다시 확인해 보세요.

1. Google AI Studio에 접속합니다.
2. 키가 활성화 상태인지 확인하세요.
3. 복사할 때 앞뒤에 공백이 들어가지 않았는지 확인합니다.

”Quota exceeded”

무료 티어 제한에 도달했습니다.

• 할당량이 초기화될 때까지 기다립니다 (매일 초기화).
• 제한 수치가 높은 Flash 모델로 바꿉니다.
• 유료 플랜으로 업그레이드합니다.

”Model not found”

모델 ID가 정확한지 확인하세요.

openclaw models list

반드시 gemini/모델-이름 형식을 사용해야 합니다.

설정하다가 여전히 막히는 부분이 있나요? AI Setup Assistant는 모든 OpenClaw 문서를 학습해서 실시간으로 Gemini 설정을 도와줄 수 있어요.

---

Gemini vs 다른 Provider

항목	Gemini	Claude	OpenAI
추천 용도	긴 문서, 멀티모달	창의적, 섬세함	코딩, 분석
무료 티어	✅ 파격적임	❌ 없음	❌ 없음
컨텍스트	1M tokens	200K tokens	128K tokens
코딩 성능	좋음	뛰어남	뛰어남

문서 처리나 가성비 좋은 fallback 모델이 필요할 때는 Gemini를 사용하세요. 최고의 결과물이 필요한 작업에는 Claude나 GPT를 쓰는 것이 좋습니다.

---

다음 단계

• OpenClaw 설치하기 → — 전체 설치 가이드
• Ollama 사용하기 → — 무료 로컬 AI 활용
• Telegram 연결하기 → — 폰에서 제어하기
• Docker 배포 → — 24시간 중단 없는 서버 구축

도움이 필요하신가요? OpenClaw Discord에 참여하거나 공식 문서를 확인해 보세요.