Gemini와 함께 사용하는 OpenClaw: 모델 설정, API 키 및 비용 확인

OpenClaw은 내장된 google 플러그인을 통해 Gemini에 연결합니다. GEMINI_API_KEY 또는 GOOGLE_API_KEY를 설정하고, openclaw onboard --auth-choice gemini-api-key를 실행한 다음 모델을 명시적으로 설정하세요. 인증을 추가해도 기본 모델은 변경되지 않기 때문입니다. 대부분의 설정 게시물이 놓치는 부분은 AI Studio 키를 사용할 때 OpenClaw에 각각 별도의 자격 증명, 엔드포인트 및 청구가 있는 세 가지 Gemini 표면이 있다는 점입니다. (Vertex AI는 gcloud Application Default Credentials를 통한 별도의 네 번째 자격 증명 경로이며 여기서는 다루지 않습니다.) 채팅이 작동한다고 해서 Gemini 검색이 활성화되는 것은 아니며, Gemini 검색을 활성화하면 채팅 경로가 전혀 사용하지 않는 Google 프로젝트에 요금이 부과될 수 있습니다.

Gemini 통합은 별도의 설치가 아닙니다. OpenClaw 자체에 번들 google 제공자 플러그인(공식 제공자 플러그인, 2026년 9월 21일)에 포함되어 있으며, OpenClaw은 MIT 라이선스로 배포되고 npm에 openclaw@2026.9.5로 게시되며 Node >=24.16.0 <25 || >=26.1.0가 필요합니다(npm 레지스트리, 2026년 9월 21일). 소프트웨어 자체는 무료이며, 아래 내용은 모두 키에 드는 비용에 관한 것입니다.

세 가지 Gemini 표면, 세 가지 자격 증명

우선순위 규칙이 핵심입니다. Gemini 웹 검색은 먼저 plugins.entries.google.config.webSearch.apiKey, 그다음 GEMINI_API_KEY, 그다음 models.providers.google.apiKey를 읽으며, 전용 webSearch.baseUrl가 models.providers.google.baseUrl보다 먼저 적용됩니다. OpenClaw은 여기서 모델 제공자 헤더를 상속하지 않습니다. 해당 헤더는 "웹 검색 엔드포인트와 다를 수 있는 모델 제공자 엔드포인트에 속하기" 때문이며, 검색 요청에서 Content-Type, x-goog-api-key 및 x-goog-api-client의 소유권을 유지합니다(Gemini 검색 문서, 2026년 9월 21일). 두 경로는 의도적으로 독립되어 있습니다.

오래된 튜토리얼을 따르기 전에 확인하세요. OpenClaw은 "새로운 Gemini CLI OAuth 또는 Antigravity OAuth 설정을 제공하지 않는다"고 명시하며, 2026년 6월 18일 소비자용 Gemini CLI Login with Google 액세스가 종료되었음을 인용합니다(제공자 문서). Google의 2026년 5월 19일 게시물은 Gemini CLI와 Code Assist IDE 확장이 Google AI Pro 및 Ultra 구독자와 무료 사용자에 대한 서비스를 중단한다고 설명합니다(Google 개발자 블로그). 두 내용 모두 CLI와 IDE 표면에 관한 것이며 AI Studio API 키에 관한 것이 아닙니다. 아래에서 설명하는 경로가 API 키 경로입니다.

Gemini API 키 설정

# The bundled google plugin reads either name.
export GEMINI_API_KEY="AIza..."   # or GOOGLE_API_KEY

openclaw onboard --auth-choice gemini-api-key

# Auth alone does not change the default model — set it on purpose.
openclaw models list --provider google
openclaw models set google/<id-from-that-list>

번들 플러그인은 순환을 위해 GEMINI_API_KEYS, GEMINI_API_KEY_1 및 GEMINI_API_KEY_2도 읽고, 단일 재정의로 OPENCLAW_LIVE_GEMINI_KEY도 읽습니다(공식 제공자 플러그인, 2026년 9월 21일). 이는 google 플러그인 자체의 변수로 문서화되어 있습니다. 사용자 자신이 선언한 제공자 id에는 사용자 지정 제공자 참조가 이를 나열하지 않으며, 해당 제공자의 키는 apiKey를 통해 설정합니다($${ENV_VAR} 확장이 해당 문서에 표시되어 있음).

마지막 줄은 보기보다 중요합니다. openclaw configure는 "제공자를 추가하거나 재인증할 때 기존 agents.defaults.model.primary를 유지"하며, openclaw models auth login도 --set-default를 전달하지 않는 한 동일하게 동작합니다(빠른 규칙). Gemini를 인증했는데도 이전 모델에서 답변을 받는 것은 버그가 아니라 예상된 동작입니다.

이 튜토리얼을 포함해 어떤 튜토리얼에서도 모델 id를 그대로 복사하지 마세요. 키가 구성되면 OpenClaw은 Gemini models.list API를 통해 Google AI Studio의 텍스트 모델 카탈로그를 새로고침하므로 OpenClaw 릴리스 없이도 새 변형이 표시됩니다. 그러나 OpenClaw 자체 페이지는 예시 id에 대해 서로 다르게 설명합니다. 한 곳에서는 google/gemini-3.5-flash, 다른 곳에서는 google/gemini-3.1-flash와 google/gemini-3.1-pro-preview를 명시하고, 검색 도구의 기본값으로는 gemini-3.6-flash를 사용합니다. 실제 목록만이 권위 있는 기준입니다. OpenClaw은 일부 레거시 참조를 정규화합니다. google/gemini-3.1-pro는 google/gemini-3.1-pro-preview로 "허용되고 정규화"되며(공식 제공자 플러그인), google/gemini-3-pro-preview는 "2026-03-09에 폐기"되었고 대체 항목으로 google/gemini-3.1-pro-preview가 지정되어 있습니다(제공자 문서, 2026년 9월 21일).

Gemini API 키가 실제로 청구하는 항목

토큰과 검색 그라운딩은 두 가지 청구 항목이며, Google 페이지는 한눈에 보면 하나처럼 읽힙니다. Google 가격 페이지에서 확인한 Standard 등급 Gemini Developer API의 1M 토큰당 요금은 다음과 같습니다(2026년 9월 16일 마지막 업데이트, 2026년 9월 21일 확인):

마지막 열은 두 번 읽어야 합니다. OpenClaw의 기본 Gemini 웹 검색 모델은 gemini-3.6-flash이며, Google의 무료 등급에서는 그라운딩이 "제공되지 않는" Gemini 3.x 모델입니다. 따라서 동일 모델의 토큰은 무료여도 기본 Gemini 검색 설정에는 유료 프로젝트가 필요합니다. 단위도 다릅니다. OpenClaw 자체는 "Gemini 3 그라운딩은 검색 쿼리별로 청구되고 Gemini 2.5 그라운딩은 프롬프트별로 청구된다"고 설명하며, Google은 요청이 "Google 검색에 하나 이상의 쿼리를 발생시킬 수 있습니다. 수행된 각 개별 검색 쿼리에 대해 요금이 부과됩니다"라고 덧붙입니다. 그라운딩 비용은 토큰 비용에 추가됩니다. "Gemini에는 항상 비용이 적용됩니다"(두 인용문 모두 동일한 가격 페이지). 예를 들어 한 달에 Gemini 3.x 검색 쿼리 6,500건을 사용하면 그중 1,500건에 1,000건당 $14가 부과되므로, 토큰 비용 전 검색 요금만 $21.00입니다.

동일한 페이지에서 확인할 사항이 두 가지 더 있습니다. 유료 등급에는 컨텍스트 캐싱과 비용이 50% 절감되는 Batch API가 추가되며, 데이터 사용 관련 항목도 달라집니다. 무료 등급 콘텐츠는 "당사 제품 개선에 사용"되지만 유료 콘텐츠는 그렇지 않으며, 이는 항상 켜진 어시스턴트에 중요합니다. Gemini는 OpenClaw의 검색 제공자 중 하나일 뿐입니다. DuckDuckGo("없음(키 불필요)"), SearXNG("없음(셀프 호스팅)") 및 Parallel Search(무료)("없음(무료 Search MCP)")는 웹 검색 제공자 표에서 키가 필요 없는 옵션으로 나열되어 있습니다(웹 검색, 2026년 9월 21일). 따라서 "Gemini 그라운딩이 정말 필요한가"는 타당한 첫 질문입니다.

OpenAI 호환 게이트웨이를 통한 Gemini 채팅 라우팅

OpenClaw의 사용자 지정 제공자 참조는 명시적 models.providers.<id> 항목을 "기본 base URL, 헤더 또는 모델 목록을 재정의하려는 경우에만" 사용하라고 하며, 게이트웨이 구성 참조는 열한 개의 api 값인 openai-completions, openai-responses, openai-chatgpt-responses, anthropic-messages, google-generative-ai, google-vertex, github-copilot, bedrock-converse-stream, ollama, pi-messages 및 azure-openai-responses를 나열합니다. v2026.9.7의 구성 스키마는 2026년 9월 25일 추가된 열두 번째 값 google-interactions도 허용합니다. 참조에는 아직 나열되지 않았지만 OpenClaw의 Google 제공자 페이지는 이를 기본 google-generative-ai 전송의 선택적 대안으로 문서화하며, https://generativelanguage.googleapis.com/v1beta에서 Gemini의 Interactions API를 사용합니다. Kunavo의 Gemini 모델은 POST /v1/chat/completions(채팅 엔드포인트)의 OpenAI 호환 표면을 통해 연결되며, Kunavo는 generativelanguage, v1beta 또는 Interactions 엔드포인트를 게시하지 않습니다. 따라서 어떤 Google 어댑터도 Kunavo에 도달하지 못하며, 도달 가능한 경로는 별도의 제공자 id이고 결코 리디렉션된 google 플러그인이 아닙니다.

{
  "models": {
    "mode": "merge",
    "providers": {
      "kunavo": {
        "baseUrl": "https://api.kunavo.com/v1",
        "apiKey": "${KUNAVO_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "gemini-3-8-flash",
            "name": "Gemini 3.8 Flash",
            "input": [
              "text",
              "image"
            ],
            "contextWindow": 1048576,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "kunavo/gemini-3-8-flash"
      }
    }
  }
}

여기서 네 가지 세부 사항이 핵심입니다. 슬러그는 대시 표기입니다. Kunavo의 id는 gemini-3-8-flash이고 Google 및 OpenClaw의 id는 점 표기이며, 서로 다른 문자열입니다. contextWindow를 선언한 이유는 컨텍스트 메타데이터가 없는 사용자 지정 모델이 200,000토큰 예산으로 폴백하기 때문입니다. 이 폴백은 여기서 Kunavo 카탈로그에 기록된 컨텍스트 창(1,048,576토큰 — Kunavo의 메타데이터이며 Google이 게시한 제한이 아님)의 대부분을 활용하지 못하게 합니다. input에는 이미지가 명시되어 있습니다. OpenClaw이 사용자 지정 모델을 기본적으로 텍스트 전용으로 설정하기 때문입니다. 또한 cost는 생략되므로 이 경로에서 OpenClaw의 로컬 추정값은 기본적으로 0입니다. $0 표시는 무료 추론이 아니라 누락된 메타데이터를 의미합니다.

이 경로에서 포기하게 되는 기능은 추측이 아니라 문서화된 내용입니다. OpenAI 자체 호스트가 아닌 호스트에 대해 api: "openai-completions"를 사용할 때 OpenClaw는 compat.supportsDeveloperRole: false를 강제하고 네이티브 요청 구성을 건너뜁니다. 즉 service_tier, Responses 또는 Completions의 store, 프롬프트 캐시 힌트, 추론 호환 페이로드 구성은 없습니다(사용자 지정 제공자). Gemini 전용 추가 기능도 제외됩니다. params.cachedContent는 Gemini를 직접 사용하는 실행에 대해 문서화되어 있고, 키 순환 변수는 플러그인 기능이며, OpenClaw의 thinkingLevel / thinkingBudget 매핑은 google 제공자에 대해 설명되어 있습니다. 게이트웨이 경로에서도 유지되는지는 이 페이지에서 확인하지 않았습니다.

Kunavo는 임베딩 모델과 텍스트 음성 변환 또는 음성 텍스트 변환 모델을 제공하지 않습니다. 따라서 google 플러그인의 임베딩 및 음성 계약은 채팅 라우팅 방식과 관계없이 Google 키를 계속 사용합니다.

기능에 관해서는 누구의 말을 따르는지 주의하세요. Google의 현재 모델 페이지에는 모델별 토큰 제한이 더 이상 표시되지 않으므로, 다른 곳에서 인용된 컨텍스트 수치는 누군가가 오래된 출처를 복사한 것입니다. Kunavo의 카탈로그는 Gemini 목록에서 비전, 함수 호출, 스트리밍 및 긴 컨텍스트를 표시하고, gemini-2-5-flash를 제외한 모든 모델에서 사고 기능을 표시합니다. 각 주장은 게시한 주체의 범위 안에서만 유효하므로 자신의 작업에서 도구 호출을 먼저 확인하세요.

실제로 선택한 모델의 가격 계산

오늘은 제품군 전체를 기준으로 비교하면 잘못되므로 Google Standard 등급과 모델별로 비교합니다:

Kunavo 요금은 실시간 카탈로그에서, Google 요금은 2026년 9월 21일에 확인한 가격 페이지에서 가져왔습니다. 도입 기간은 2026년 12월 31일에 종료되며, 이후 Flash 비교는 다시 반전됩니다.

계산 예시는 측정된 OpenClaw 작업이나 청구 상한이 아니라 토큰 산술입니다. 캐싱과 검색 없이 일주일 동안 어시스턴트 작업을 수행하며 캐시되지 않은 입력 토큰 4,000,000개를 보내고 출력 토큰 150,000개를 받는다고 가정하세요. Kunavo 요금의 Gemini 3.8 Flash에서는 $2.49입니다. Google의 도입 Flash 요금으로 같은 산술을 적용하면 $3.56이고, 2027년 요금에서는 $7.13로 증가합니다. Gemini 3.6 Flash에서 같은 양을 Kunavo 요금으로 사용하면 $4.99이 됩니다. 이는 Google 도입 요금보다 높으며, 바로 그렇기 때문에 결정 기준은 제공자 이름이 아니라 모델 id입니다.

Kunavo의 카탈로그 금액은 상한이 아니라 청구 하한입니다. 업스트림이 요금을 보고하면 청구액은 카탈로그 비용과 업스트림 비용에 적용 가능한 마크업을 곱한 값 중 더 큰 금액입니다. 캐시 요금, 검색 그라운딩 및 호스팅은 이 예시에서 제외되며, 최소 충전액은 $10의 선불 크레딧입니다. 이는 작업 요금이나 구독료가 아니라 자금 충전 최소액입니다. 전체 운영 청구액은 청구 세부 정보와 OpenClaw 가격을 참조하세요.

요청 하나로 확인한 다음 두 장부를 모두 읽기

openclaw config validate
openclaw gateway restart
openclaw models list --provider kunavo
openclaw infer model run --model kunavo/gemini-3-8-flash --prompt "hi" --json

openclaw models list는 게시된 인벤토리를 읽고 openclaw models status는 확인된 기본값과 인증 상태를 표시합니다. 둘 다 유료 작업이 성공한다는 증거는 아니며, 알려진 제공자에서 openclaw models set를 사용하면 카탈로그에 없는 모델을 경고만 표시한 채 저장합니다. openclaw doctor --json --severity-min info는 로컬 카탈로그가 확인할 수 없는 활성 모델도 표시합니다(CLI 참조). 위의 단일 요청이 비용이 발생하는 첫 번째 증거입니다.

상태 코드별로 분류하세요. OpenClaw은 로컬 OpenAI 호환 서버의 model_not_found 패턴과, 사용자 지정 제공자 항목이 설정하는 동일한 세 필드를 문서화합니다. baseUrl에 /v1가 포함되어 있는지, /v1/chat/completions 백엔드에는 api가 "openai-completions"인지, models[].id가 제공자 로컬의 순수 id인지 확인하세요. 제공자 접두사는 선택 시점에만 사용합니다(문제 해결). Kunavo에서 기본 URL이 올바른지 알려주는 확인 방법은 실제 API 경로에 인증 없이 요청하는 것입니다. GET https://api.kunavo.com/v1/models는 401를 authentication_error 본문과 함께 반환하며, 이는 URL은 올바르지만 키는 올바르지 않다는 뜻입니다. 순수 호스트와 순수 /v1 경로는 API 경로가 아니며 HTML을 반환하므로, 둘 중 하나를 가리키는 클라이언트는 모델에 도달하기 전에 실패합니다(2026년 9월 21일 확인). 403은 멈추고 읽어야 하는 상태입니다. OpenClaw은 403이 "CDN, WAF, 봇 관리 규칙 또는 역방향 프록시와 같은 업스트림 보안 계층에서 발생할 수 있다"고 경고하며, 최소 curl이 성공해도 실제 SDK 스타일 요청이 동일한 계층을 통과한다는 보장은 없다고 설명합니다. 자세한 내용은 모델을 찾을 수 없음 및 Gemini API 키가 작동하지 않음을 참조하세요.

네이티브 경로에서는 Kunavo의 Gemini API 키 안내와 Google AI Studio에서 시작하세요. 게이트웨이 경로에서는 API 키에서 키를 만들고 Kunavo 계정 열기를 수행한 다음 OpenClaw에 가장 적합한 API의 사용자 지정 제공자 안내를 따르세요. 테스트하는 동안 작동 중인 경로를 계속 사용할 수 있게 유지하세요.

어떤 경우에 어떤 경로가 적합한가

아직 제공자를 구성하지 않고 선택하는 중이라면 Gemini API 가격과 OpenAI 호환 API가 이 결정의 두 부분을 다룹니다.

자주 묻는 질문

2026년 9월 21일 이 페이지를 위해 가져온 자료: OpenClaw의 Google 제공자, 공식 제공자 플러그인, Gemini 검색, 웹 검색, 사용자 지정 제공자(개념 및 게이트웨이 참조 모두), 빠른 규칙, CLI 모델 및 문제 해결 문서; Google의 Gemini API 가격 페이지(2026년 9월 16일 마지막 업데이트), 모델 페이지, Google 검색 그라운딩 페이지 및 2026년 5월 19일 개발자 블로그 게시물; openclaw의 npm 레지스트리 항목; Kunavo 자체 카탈로그입니다. 2026년 10월 1일 사용자 지정 제공자의 api 값은 게이트웨이 참조, Google 제공자 페이지, 구성 스키마 및 v2026.9.7 소스의 Interactions 전송을 기준으로 다시 확인했습니다. 이 페이지에서 수행한 유일한 실시간 요청은 위의 401을 기록하기 위해 Kunavo의 /v1/models에 보낸 인증 없는 GET였습니다. OpenClaw 설치, Kunavo 엔드포인트 또는 Google을 대상으로 한 런타임 테스트는 수행하지 않았습니다. 모든 금액은 게시된 요금을 바탕으로 한 예시 산술입니다.