Google AI Pro 구독 플랜으로 추가 과금 없이 OpenClaw에서 Gemini 모델 사용하기

Google AI Pro 구독을 OpenClaw fallback 모델로 쓰고 싶었다. 알 수 없는 사용량 소모 문제 때문에 한 번 해지했다가, GitHub 이슈와 Discord에서 해결책 찾고 다시 연동에 성공했다.

들어가며

OpenClaw는 여러 LLM 프로바이더를 fallback 체인으로 엮어 쓸 수 있다. Anthropic, OpenAI Codex, Moonshot 외에 Google Gemini도 google-gemini-cli 프로바이더를 통해 연동할 수 있는데, API 키 방식이 아니라 Google CLI OAuth 방식을 쓰면 별도 API 비용 없이 Google AI Pro 구독만으로 OpenClaw에서 사용할 수 있다. 혹시 Gemini CLI가 설치돼 있지 않다면 먼저 설치하고 돌아오시길..

주의! OpenClaw에서 Google AI 구독 모델을 통한 OAuth 인증 방식은 비공식이다. OpenClaw 공식 문서에도 "unofficial integration, some users have reported Google account restrictions"라고 명시돼 있다. 최악의 경우, 계정이 차단될 수도 있으니 이를 인지하고 진행하기 바란다. OpenClaw 전용 서브 구글 계정을 만들어서 사용하는 것도 나름의 방법이다.

 

TL;DR 빠른 설정 (2단계)

조금 긴 글이 될 것 같다. 시간이 없다면 따라하기 식으로 아래 2단계만 수행하면 바로 OpenClaw에서 Gemini 모델을 사용할 수 있다.

1단계: 플러그인 활성화 + OAuth 로그인

먼저 google 플러그인을 활성화한다. OpenClaw의 Google/Gemini CLI 연동 기능은 google 플러그인으로 제공된다. 기본 설치 시 대부분 이미 활성화돼 있으며, 중복 실행해도 무시된다.

openclaw plugins enable google

다음으로 OAuth 로그인을 진행한다.

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

Yes를 선택하고 진행하면 브라우저 창이 뜬다. Google AI Pro 구독에 연결된 구글 계정으로 로그인한다.

구글 로그인 후, 위와 같은 화면에서 '로그인' 버튼을 클릭하면 OAuth 인증이 완료된다.

 

2단계: 게이트웨이 재시작

openclaw gateway restart

터미널에서 위의 명령어로 게이트웨이를 재시작한다. 이어서 'openclaw models' 명령을 실행해서 아래와 같이 "google-gemini-cli usage: Pro 100% left" 또는 "google-gemini-cli:your@gmail.com ok expires in Xm" 같은 구문이 표시돼야 한다.

주의! 구글 구독 모델을 통한 OAuth 인증 방식은 비공식이다. OpenClaw 공식 문서에도 "unofficial integration, some users have reported Google account restrictions"라고 명시돼 있다. Google 약관을 확인하고, 중요하지 않은 계정으로 사용할 것을 권장한다.

핵심만 빠르게 설명했는데 혹시 중간에 막히거나, 단순한 따라하기가 아닌 자세한 설명이 필요한 분들은 스크롤을 쭉 내려서 '실제 설정 과정 (상세)' 챕터를 읽어보시기 바란다.

 

삽질 기록 (건너뛰어도 됨)

지금은 깔끔하게 정리된 버전으로 설치 방법을 써놨지만 삽질이 좀 있었다. 나중에 비슷한 문제가 생기면 (내가) 보려고 참고용으로 기록해 둔다.

이슈 발생 - 얼마 쓰지 않았는데 금세 사용량 한도에 걸림

처음 연동 직후 Google AI Pro 사용량 대시보드에서 예상보다 빠르게 쿼터가 줄어드는 걸 발견했다. 원인을 추적해보니 두 가지가 겹쳐 있었다.

첫 번째: Discord에서 model picker로 Gemini Pro를 한 번 선택했는데, 그게 크론 세션에 modelOverride로 캐시 됐다. 크론 설정 자체엔 모델 지정이 없었는데도 세션 캐시 때문에 크론이 돌 때마다 Gemini Pro 쿼터를 소비하고 있었다. 크론들에 명시적으로 모델을 지정하는 것으로 해결했다.

두 번째: openclaw models auth login 시 'loadCodeAssist failed: 400 Bad Request' 에러가 간헐적으로 발생했다. 당시 2026.3.1 버전의 OAuth 처리 버그였는데, 2026.3.2에서 수정됐다.

OpenClaw 최신 버전을 사용 중이라면 위의 두 문제(크론 캐시, loadCodeAssist 버그)가 더 이상 발생하지 않는다. 당시 두 가지 문제를 스스로 해결한 과정을 설명한다.

해결의 실마리 - GitHub 이슈에서 단서

원인 파악 과정에서 OpenClaw 공식 레포에서 관련 이슈를 찾았다.

👉 openclaw/openclaw PR #29598 - loadCodeAssist 400 에러 처리 개선

fix(auth): handle Gemini CLI loadCodeAssist 400 during OAuth by pandego · Pull Request #29598 · openclaw/openclaw

결정적 단서 - Discord에서 핵심 설정 발견

OpenClaw Discord 서버의 #help 채널 스레드에서 OpenClaw 팀원(Krill)이 설명한 내용:

👉 OpenClaw Discord #help 스레드

Discord - Group Chat That’s All Fun & Games

• 구글 플러그인은 먼저 loadCodeAssist를 시도해서 Google Cloud 프로젝트를 찾는다.
• GOOGLE_CLOUD_PROJECT 환경변수가 설정돼 있으면 그 값으로 Pro 구독 한도에 연결된다.
• 이 설정이 없으면 free-tier로 fallback 될 수 있다.

이게 핵심이었다. 버그 픽스가 아니라 원래 설계상 프로젝트 ID를 명시해 줘야 Pro 구독 한도가 제대로 잡힌다. 그리고 이 설정은 현재 최신 버전에서도 여전히 유효하다. 아래 '실제 설정 과정' 챕터에서 자세히 설명한다.

Free tier vs Pro 구독 한도

위에서 free tier 얘기를 꺼낸 김에 조금 더 설명한다. Google Gemini CLI 사용에는 두 가지 경로가 있다.

Free tier (무료 일일 할당량): Google 계정이 있으면 누구나 쓸 수 있다. 돈이 나가지 않는 대신 요청 수에 제한이 있다. 예를 들어 gemini-2.0-flash는 분당 15회, 하루 1,500회 정도다. OpenClaw를 몇 가지 작업에만 쓴다면 충분할 수 있지만, 크론이나 멀티 에이전트 환경에선 금방 한도에 걸린다.

Pro 구독 한도 (Google AI Pro): 월 ₩29,000짜리 구독에 포함된 Gemini CLI 사용 한도다. Free tier보다 훨씬 높은 일일 요청 수를 제공한다. 로그인 시 auth profile에 projectId가 자동으로 저장되고, OpenClaw가 이 값을 직접 읽어 Pro 한도와 연결한다. GOOGLE_CLOUD_PROJECT 환경변수를 별도로 설정하지 않아도 된다.

 

실제 설정 과정 (상세)

1. Google Cloud 프로젝트 API 활성화

Google Cloud Console의 API 설정 페이지에 접속한다.

https://console.cloud.google.com/apis/library

Google Cloud console

해당 페이지에서 OpenClaw에서 사용할 'Google Cloud 프로젝트'를 선택하고, Gemini for Google Cloud'를 검색한 후 활성화(Enable) 처리한다.

Gemini CLI를 이미 사용 중이라면 이미 활성화돼 있을 수 있다. 즉, 이미 'API 사용 설정됨' 상태라면 따로 할 게 없다. 참고로 Google Cloud 프로젝트를 생성하는 방법은 아래 포스트에서 'Google Cloud 프로젝트 생성'으로 검색하면 찾을 수 있다.

https://bongman.tistory.com/1253

OpenClaw 활용 가이드 - 이메일 계정을 연동하고 특정 메일만 필터링해서 알림 받기

 

2. GOOGLE_CLOUD_PROJECT 설정

~/.openclaw/.env 파일에 Google Cloud 프로젝트 ID를 지정한다. 프로젝트 ID는 Google Cloud Console 페이지에서 확인할 수 있다.

위 그림과 같이 프로젝트 선택 창의 ID 항목(gen-lang-client~)이 프로젝트 ID다. 아래와 같이 ~/.openclaw/.env 파일에 Google Cloud 프로젝트 ID를 지정한다.

echo "GOOGLE_CLOUD_PROJECT=your-project-id" >> ~/.openclaw/.env

나중에 OAuth 인증을 완료한 후에 아래와 같은 명령어로 확인할 수도 있다.

cat ~/.openclaw/agents/main/agent/auth-profiles.json | python3 -c "
import json, sys
d = json.load(sys.stdin)
for k, v in d.get('profiles', {}).items():
    if 'gemini-cli' in k:
        print('projectId:', v.get('projectId', 'not found'))
"

 

3. Gemini CLI OAuth 로그인

openclaw models auth login

선택지에서 Gemini CLI OAuth 선택한다.

이후 위와 같은 경고 문구가 표시된다. Google이 비공식 OAuth 클라이언트를 통한 Gemini CLI OAuth 접근을 제한하기 시작했고, Google Antigravity 사용자들 사이에서 계정 제한 보고가 나오고 있다. 이러한 위험성을 인식하고 진행하라는 경고다. 글 서두에 언급했지만 계정이 제한될 수도 있으니 이를 인지하고 이후 절차를 진행하기 바란다.

Yes를 선택하면 브라우저 창이 뜬다. Gemini AI Pro 구독에 연동된 Google 계정으로 로그인한다.

'로그인'을 클릭한다.

브라우저에 인증이 완료됐다는 문구가 표시된다.

터미널로 다시 돌아온다. 위와 같이 'Gemini CLI OAuth complete'라는 문구가 표시되면 인증 성공이다.

터미널에서 'openclaw models' 명령을 실행해서 위와 같이 "google-gemini-cli usage: Pro 100% left" 또는 "google-gemini-cli:your@gmail.com ok expires in Xm" 같은 구문이 표시되는 것을 확인한다.

 

4. 게이트웨이 재시작

마지막 단계다. OpenClaw 게이트웨이를 재시작한다.

openclaw gateway restart

 

연동 확인

터미널에서 아래 명령어를 실행한다.

openclaw models

OAuth/token status 섹션에 아래와 같이 표시되면 정상적으로 OAuth 인증이 완료된 것이다.

'ok expires in Xm' 구문이 핵심인데 OAuth 토큰이 유효하다는 뜻이다. OpenClaw에서 Gemini 모델을 API 건당 과금이 아니라 구독 한도 내에서 사용할 수 있는 것이다. 끝.