OpenClaw com Gemini: configuração do modelo, chaves de API e verificações de custo

O OpenClaw acessa o Gemini por meio do plugin google incluído: defina GEMINI_API_KEY ou GOOGLE_API_KEY, execute openclaw onboard --auth-choice gemini-api-key e depois defina o modelo explicitamente — pois adicionar a autenticação não altera seu modelo padrão. O ponto que a maioria das publicações de configuração não aborda é que, com uma chave do AI Studio, o OpenClaw tem três superfícies Gemini separadas, cada uma com sua própria credencial, endpoint e cobrança. (O Vertex AI é um quarto caminho de credencial separado, por meio das Application Default Credentials do gcloud, e não é abordado aqui.) Fazer o chat funcionar não habilita a pesquisa do Gemini, e habilitar a pesquisa do Gemini pode gerar uma cobrança em um projeto Google que sua rota de chat nunca utiliza.

A integração com o Gemini não é uma instalação separada. Ela vem dentro do próprio OpenClaw como o plugin de provedor google incluído (plugins de provedores oficiais, 21 de setembro de 2026), e o OpenClaw é licenciado pelo MIT e publicado como openclaw@2026.9.5 no npm, exigindo Node >=24.16.0 <25 || >=26.1.0 (registro do npm, 21 de setembro de 2026). O software não custa nada; tudo abaixo trata do custo das chaves.

Três superfícies Gemini, três credenciais

As regras de precedência são a parte útil. A pesquisa na web do Gemini lê plugins.entries.google.config.webSearch.apiKey primeiro, depois GEMINI_API_KEY, depois models.providers.google.apiKey, e o webSearch.baseUrl dedicado tem prioridade sobre models.providers.google.baseUrl. O OpenClaw também não herda os cabeçalhos do provedor do modelo aqui, porque eles "pertencem ao endpoint do provedor do modelo, que pode ser diferente do endpoint de pesquisa na web", e mantém a propriedade de Content-Type, x-goog-api-key e x-goog-api-client na solicitação de pesquisa (documentação da pesquisa do Gemini, 21 de setembro de 2026). Duas rotas, deliberadamente independentes.

Antes de seguir um tutorial antigo: o OpenClaw informa que "não oferece nova configuração de OAuth do Gemini CLI nem de OAuth do Antigravity", citando o fim do acesso do consumidor ao Gemini CLI Login with Google em 18 de junho de 2026 (documentação do provedor). A própria publicação do Google de 19 de maio de 2026 informa que o Gemini CLI e as extensões do Code Assist para IDE deixam de atender assinantes do Google AI Pro e Ultra e usuários gratuitos (blog de desenvolvedores do Google). Ambas as afirmações se referem à superfície de CLI e IDE, não às chaves de API do AI Studio — o caminho da chave de API é o apresentado abaixo.

Definindo a chave de API do Gemini

# 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>

O plugin incluído também lê GEMINI_API_KEYS, GEMINI_API_KEY_1 e GEMINI_API_KEY_2 para rotação e OPENCLAW_LIVE_GEMINI_KEY como uma substituição única (plugins de provedores oficiais, 21 de setembro de 2026). Essas variáveis são documentadas como próprias do plugin google; a referência de provedores personalizados não as lista para um id de provedor que você mesmo declare, que define sua chave por meio de apiKey ($${ENV_VAR} expansão é mostrada ali).

A última linha é mais importante do que parece. openclaw configure "preserva um agents.defaults.model.primary existente quando você adiciona ou reautentica um provedor", e openclaw models auth login faz o mesmo, a menos que você passe --set-default (regras rápidas). Autenticar o Gemini e continuar recebendo respostas do modelo antigo é o comportamento esperado, não um bug.

Não copie um id de modelo de nenhum tutorial, inclusive deste. Com uma chave configurada, o OpenClaw atualiza o catálogo de modelos de texto do Google AI Studio pela API Gemini models.list, portanto novas variantes aparecem sem uma versão nova do OpenClaw — e as próprias páginas do OpenClaw discordam sobre o id de exemplo, nomeando google/gemini-3.5-flash em um local, google/gemini-3.1-flash e google/gemini-3.1-pro-preview em outro, e definindo gemini-3.6-flash como padrão da ferramenta de pesquisa. A lista ativa é a única autoridade. O OpenClaw normaliza algumas referências antigas — google/gemini-3.1-pro é "aceito e normalizado" para google/gemini-3.1-pro-preview (plugins de provedores oficiais) — e google/gemini-3-pro-preview "foi descontinuado em 2026-03-09", com google/gemini-3.1-pro-preview indicado como substituto (documentação do provedor, 21 de setembro de 2026).

O que uma chave de API do Gemini realmente cobra

Tokens e grounding de pesquisa são dois itens de cobrança, e a página do Google parece ser uma coisa só à primeira vista. Tarifas do Gemini Developer API no nível Standard por 1 milhão de tokens, da página de preços do Google (atualizada pela última vez em 16 de setembro de 2026, lida em 21 de setembro de 2026):

Leia a última coluna duas vezes. O modelo padrão de pesquisa na web do Gemini no OpenClaw é gemini-3.6-flash, um modelo Gemini 3.x cujo grounding é "Não disponível" no nível gratuito do Google — portanto, a configuração de pesquisa do Gemini pronta para uso exige um projeto faturado, embora os tokens do mesmo modelo sejam gratuitos. As unidades também diferem: o próprio OpenClaw observa que "o grounding do Gemini 3 é cobrado por consulta de pesquisa, enquanto o grounding do Gemini 2.5 é cobrado por prompt", e o Google acrescenta que uma solicitação "pode resultar em uma ou mais consultas ao Google Search. Você será cobrado por cada consulta individual realizada". O grounding é adicionado ao custo dos tokens — "Os custos do Gemini sempre se aplicam" (ambas as citações da mesma página de preços). Por exemplo, um mês com 6.500 consultas de pesquisa Gemini 3.x cobra 1.500 delas a $14 por 1.000, ou $21.00 somente em taxas de pesquisa, antes de quaisquer tokens.

Mais duas informações da mesma página: o nível pago adiciona cache de contexto e uma Batch API com redução de custo de 50%, e inverte o item sobre uso de dados — o conteúdo do nível gratuito é "usado para melhorar nossos produtos", enquanto o conteúdo pago não é, algo importante para um assistente sempre ativo. O Gemini também é apenas um dos provedores de pesquisa do OpenClaw; DuckDuckGo ("Nenhum (sem chave)"), SearXNG ("Nenhum (auto-hospedado)") e Parallel Search (Gratuito) ("Nenhum (Search MCP gratuito)") são listados como opções sem chave na tabela de provedores de pesquisa na web (pesquisa na web, 21 de setembro de 2026), portanto "eu realmente preciso do grounding do Gemini?" é uma primeira pergunta válida.

Encaminhando o chat do Gemini por um gateway compatível com OpenAI

A referência de provedores personalizados do OpenClaw diz para usar entradas models.providers.<id> explícitas "somente quando você quiser substituir a URL base, os cabeçalhos ou a lista de modelos padrão", e a referência de configuração do gateway lista onze valores api: openai-completions, openai-responses, openai-chatgpt-responses, anthropic-messages, google-generative-ai, google-vertex, github-copilot, bedrock-converse-stream, ollama, pi-messages e azure-openai-responses. O esquema de configuração na v2026.9.7 aceita um décimo segundo, google-interactions, adicionado em 25 de setembro de 2026. A referência ainda não o lista, mas a página do provedor Google do OpenClaw o documenta como uma alternativa opcional ao transporte padrão google-generative-ai, usando a API Interactions do Gemini sob https://generativelanguage.googleapis.com/v1beta. Os modelos Gemini da Kunavo são acessados pela sua superfície compatível com OpenAI em POST /v1/chat/completions (endpoint de chat), e a Kunavo não publica generativelanguage, v1beta nem um endpoint Interactions — portanto nenhum dos adaptadores Google chega até ela, e a rota acessível é um id de provedor separado, nunca um plugin google redirecionado.

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

Quatro detalhes ali são essenciais. O slug usa hífens — o id da Kunavo é gemini-3-8-flash, enquanto os do Google e do OpenClaw usam pontos, e são strings diferentes. contextWindow é declarado porque um modelo personalizado sem metadados de contexto recorre a um orçamento de 200.000 tokens, desperdiçando a maior parte da janela registrada aqui no catálogo da Kunavo (1.048.576 tokens — metadados da Kunavo, não um limite publicado pelo Google). input nomeia imagens porque o OpenClaw define um modelo personalizado como somente texto por padrão. E cost é omitido, portanto a estimativa local do OpenClaw assume zero nessa rota: uma leitura de $0 significa que faltam metadados, não que a inferência é gratuita.

O que essa rota deixa de oferecer é documentado, não presumido. Em api: "openai-completions" contra um host que não pertence à própria OpenAI, o OpenClaw força compat.supportsDeveloperRole: false e ignora a formatação nativa da solicitação — sem service_tier, sem store de Responses ou Completions, sem dicas de cache de prompt, sem formatação de payload compatível com raciocínio (provedores personalizados). Os extras específicos do Gemini também ficam de fora: params.cachedContent é documentado para execuções diretas do Gemini, as variáveis de rotação de chaves são recursos do plugin, e o mapeamento thinkingLevel / thinkingBudget do OpenClaw é descrito para o provedor google — esta página não verificou se ele sobrevive a uma rota de gateway.

A Kunavo não oferece modelo de embeddings nem modelo de texto para fala ou fala para texto. Portanto, os contratos de embeddings e fala do plugin google permanecem em uma chave Google, independentemente de como o chat é encaminhado.

Quanto às capacidades, tenha cuidado com a fonte da informação. A página atual de modelos do Google não exibe mais limites de tokens por modelo, portanto um valor de contexto citado em qualquer outro lugar é uma cópia de uma fonte mais antiga feita por alguém. O catálogo da Kunavo sinaliza visão, chamadas de função, streaming e contexto longo nas suas listagens Gemini, e indica raciocínio em todos, exceto gemini-2-5-flash. Cada afirmação está limitada ao que foi publicado por sua respectiva fonte — verifique primeiro as chamadas de ferramentas na sua própria tarefa.

Defina o preço do modelo que você realmente escolheu

Por modelo, comparado ao nível Standard do Google, porque a versão desta comparação para toda a família é falsa hoje:

As tarifas da Kunavo vêm do catálogo vigente, e as do Google vêm da página de preços lida em 21 de setembro de 2026; a janela introdutória termina em 31 de dezembro de 2026, depois do que a comparação do Flash se inverte novamente.

Uma estimativa prática, que é cálculo de tokens e não uma tarefa medida do OpenClaw nem um teto de cobrança. Considere uma semana de trabalho do assistente enviando 4.000.000 de tokens de entrada não armazenados em cache e recebendo 150.000 tokens de saída, sem cache e sem pesquisa. Em Gemini 3.8 Flash com as tarifas da Kunavo, isso dá $2.49; o mesmo cálculo com a tarifa introdutória do Flash do Google dá $3.56, aumentando para $7.13 com a tarifa de 2027. Execute os mesmos volumes em Gemini 3.6 Flash na Kunavo e obtenha $4.99 — acima do valor introdutório do Google, exatamente por isso o id do modelo, e não o nome do provedor, é o fator decisivo.

O valor do catálogo da Kunavo é um piso de cobrança, não um teto: quando o upstream informa sua cobrança, a fatura é o maior valor entre o custo do catálogo e o custo do upstream multiplicado pelo markup aplicável. As cobranças de cache, o grounding de pesquisa e a hospedagem ficam fora deste exemplo, e a recarga mínima é de $10 em crédito pré-pago — um mínimo de financiamento, não uma taxa por tarefa nem uma assinatura. Consulte detalhes de cobrança e preços do OpenClaw para a cobrança operacional completa.

Verifique com uma solicitação e, em seguida, leia ambos os livros-razão

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 lê o inventário publicado e openclaw models status mostra o padrão resolvido e o estado de autenticação; nenhum dos dois prova que uma tarefa paga funciona, e openclaw models set em um provedor conhecido salva um modelo não catalogado apenas com um aviso. openclaw doctor --json --severity-min info também exibe modelos ativos que o catálogo local não consegue confirmar (referência da CLI). A única solicitação acima é a primeira evidência de que há custos envolvidos.

Faça a triagem pelo código de status. O OpenClaw documenta a assinatura model_not_found para um servidor local compatível com OpenAI, e os três campos que ele nomeia são os mesmos três definidos por uma entrada de provedor personalizado: verifique se baseUrl inclui /v1, se api é "openai-completions" para um back-end /v1/chat/completions, e se models[].id é o ID local simples do provedor, usando o prefixo do provedor apenas no momento da seleção (solução de problemas). Contra o Kunavo, a verificação que informa se a URL base está correta é uma solicitação não autenticada a um caminho de API real: GET https://api.kunavo.com/v1/models responde 401 com um corpo authentication_error, o que significa que a URL está correta e a chave não está. O host simples e o caminho /v1 simples não são caminhos de API e respondem com HTML, portanto um cliente apontado para qualquer um deles falhará antes mesmo de chegar a um modelo (verificado em 21 de setembro de 2026). Um 403 é o único caso em que você deve parar e investigar: o OpenClaw alerta que ele "pode vir de uma camada de segurança upstream, como uma CDN, WAF, regra de gerenciamento de bots ou proxy reverso", e que um curl mínimo bem-sucedido não garante que solicitações reais no estilo de SDK passem pela mesma camada. Consulte modelo não encontrado e chave de API do Gemini não funciona para as versões mais longas.

Para a rota nativa, comece pelas notas do Kunavo sobre a chave de API do Gemini e pelo Google AI Studio; para a rota do gateway, crie uma chave em Chaves de API e abra uma conta Kunavo, depois siga o guia do provedor personalizado em melhor API para OpenClaw. Mantenha sua rota funcional disponível enquanto testa.

Qual rota vence quando

Se você ainda está escolhendo um provedor em vez de configurá-lo, preços da API do Gemini e API compatível com OpenAI cobrem as duas metades dessa decisão.

Perguntas frequentes

Obtido para esta página em 21 de setembro de 2026: a documentação do OpenClaw sobre provedor do Google, plug-ins de provedores oficiais, pesquisa do Gemini, pesquisa na web, provedor personalizado (tanto os conceitos quanto a referência do gateway), regras rápidas, modelos da CLI e solução de problemas; a página de preços da API do Gemini do Google (atualizada pela última vez em 16 de setembro de 2026), sua página de modelos, sua página de grounding do Google Search e sua publicação no blog de desenvolvedores de 19 de maio de 2026; a entrada do registro npm para openclaw; e o próprio catálogo do Kunavo. Em 1º de outubro de 2026, os valores de api do provedor personalizado foram verificados novamente contra a referência do gateway, a página do provedor do Google e o esquema de configuração e o transporte Interactions do OpenClaw em seu código-fonte na v2026.9.7. A única solicitação ao vivo feita para esta página foi um GET não autenticado para /v1/models do Kunavo, para registrar o 401 descrito acima. Nada aqui foi testado em runtime contra uma instalação do OpenClaw, no endpoint do Kunavo ou nos do Google; todos os valores em dólares são aritmética ilustrativa baseada nas tarifas publicadas.