OpenClaw con Gemini: configuración del modelo, claves API y comprobación de costes

OpenClaw accede a Gemini mediante su plugin google incluido: configura GEMINI_API_KEY o GOOGLE_API_KEY, ejecuta openclaw onboard --auth-choice gemini-api-key y después establece explícitamente el modelo, porque añadir la autenticación no cambia el modelo predeterminado. Lo que la mayoría de las publicaciones de configuración omiten es que, con una clave de AI Studio, OpenClaw ofrece tres superficies de Gemini separadas, cada una con sus propias credenciales, endpoint y coste. (Vertex AI es una cuarta ruta de credenciales independiente mediante las credenciales predeterminadas de aplicación de gcloud, y no se trata aquí). Hacer funcionar el chat no habilita la búsqueda de Gemini, y habilitar la búsqueda de Gemini puede generar un cargo en un proyecto de Google que la ruta de chat nunca utiliza.

La integración de Gemini no se instala por separado. Se incluye en el propio OpenClaw como el plugin de proveedor google incluido (plugins de proveedores oficiales, 21 de septiembre de 2026), y OpenClaw cuenta con licencia MIT y se publica como openclaw@2026.9.5 en npm, requiriendo Node >=24.16.0 <25 || >=26.1.0 (registro de npm, 21 de septiembre de 2026). El software no cuesta nada; todo lo siguiente trata sobre el coste de las claves.

Tres superficies de Gemini, tres credenciales

Las reglas de precedencia son la parte útil. La búsqueda web de Gemini lee primero plugins.entries.google.config.webSearch.apiKey, después GEMINI_API_KEY y luego models.providers.google.apiKey, y el webSearch.baseUrl específico prevalece antes que models.providers.google.baseUrl. OpenClaw también decide no heredar aquí las cabeceras del proveedor del modelo, porque «pertenecen al endpoint del proveedor del modelo, que puede diferir del endpoint de búsqueda web», y mantiene la propiedad de Content-Type, x-goog-api-key y x-goog-api-client en la solicitud de búsqueda (documentación de búsqueda de Gemini, 21 de septiembre de 2026). Dos rutas deliberadamente independientes.

Antes de seguir un tutorial antiguo: OpenClaw afirma que «no ofrece una nueva configuración de OAuth de Gemini CLI ni de Antigravity OAuth», citando el fin del acceso de Gemini CLI Login with Google para consumidores el 18 de junio de 2026 (documentación del proveedor). La publicación propia de Google del 19 de mayo de 2026 indica que las extensiones de Gemini CLI y Code Assist para IDE dejan de prestar servicio a los suscriptores de Google AI Pro y Ultra y a los usuarios gratuitos (blog de desarrolladores de Google). Ambas afirmaciones se refieren a la superficie de CLI e IDE, no a las claves de API de AI Studio: la ruta de clave de API es la que se muestra a continuación.

Configuración de la clave de API de 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>

El plugin incluido también lee GEMINI_API_KEYS, GEMINI_API_KEY_1 y GEMINI_API_KEY_2 para la rotación, y OPENCLAW_LIVE_GEMINI_KEY como una única anulación (plugins de proveedores oficiales, 21 de septiembre de 2026). Están documentadas como variables propias del plugin google; la referencia de proveedores personalizados no las enumera para un id de proveedor que declares tú mismo, cuya clave se configura mediante apiKey (allí se muestra la expansión de $${ENV_VAR}).

La última línea importa más de lo que parece. openclaw configure «conserva un agents.defaults.model.primary existente cuando añades o vuelves a autenticar un proveedor», y openclaw models auth login hace lo mismo salvo que pases --set-default (reglas rápidas). Autenticar Gemini y seguir obteniendo respuestas del modelo antiguo es un comportamiento esperado, no un error.

No copies ningún id de modelo de un tutorial, incluido este. Con una clave configurada, OpenClaw actualiza el catálogo de modelos de texto de Google AI Studio mediante la API Gemini models.list, por lo que las nuevas variantes aparecen sin una versión de OpenClaw; además, las propias páginas de OpenClaw discrepan sobre el id de ejemplo: nombran google/gemini-3.5-flash en un lugar, google/gemini-3.1-flash y google/gemini-3.1-pro-preview en otro, y configuran la herramienta de búsqueda con gemini-3.6-flash de forma predeterminada. La lista actual es la única autoridad. OpenClaw normaliza algunas referencias antiguas: google/gemini-3.1-pro se «acepta y normaliza» como google/gemini-3.1-pro-preview (plugins de proveedores oficiales), y google/gemini-3-pro-preview «se retiró el 2026-03-09», con google/gemini-3.1-pro-preview como reemplazo (documentación del proveedor, 21 de septiembre de 2026).

Qué cobra realmente una clave de API de Gemini

Los tokens y la fundamentación mediante búsquedas son dos conceptos de facturación, aunque la página de Google parece una sola a primera vista. Las tarifas de Gemini Developer API del nivel estándar se expresan por cada 1M de tokens, según la página de precios de Google (actualizada por última vez el 16 de septiembre de 2026, consultada el 21 de septiembre de 2026):

Lee dos veces la última columna. El modelo de búsqueda web de Gemini predeterminado de OpenClaw es gemini-3.6-flash, un modelo Gemini 3.x cuya fundamentación aparece como «No disponible» en el nivel gratuito de Google; por tanto, la configuración de búsqueda de Gemini lista para usar necesita un proyecto con facturación, aunque los tokens del mismo modelo sean gratuitos. Las unidades también difieren: el propio OpenClaw señala que «la fundamentación de Gemini 3 se factura por consulta de búsqueda, mientras que la fundamentación de Gemini 2.5 se factura por indicación», y Google añade que una solicitud «puede generar una o más consultas a Google Search. Se te cobrará por cada consulta individual realizada». La fundamentación se suma al coste de los tokens: «Los costes de Gemini siempre se aplican» (ambas citas proceden de la misma página de precios). A modo ilustrativo, un mes con 6.500 consultas de búsqueda de Gemini 3.x factura 1.500 de ellas a $14 por cada 1.000, es decir, $21.00 solo en tarifas de búsqueda, antes de cualquier token.

Hay otras dos cuestiones en la misma página: el nivel de pago añade almacenamiento en caché del contexto y una Batch API con una reducción del coste del 50 %, y cambia el punto sobre el uso de datos: el contenido del nivel gratuito se «utiliza para mejorar nuestros productos», mientras que el contenido de pago no, algo importante para un asistente siempre activo. Gemini es además solo uno de los proveedores de búsqueda de OpenClaw; DuckDuckGo («Ninguna, sin clave»), SearXNG («Ninguna, autoalojado») y Parallel Search (Free) («Ninguna, Search MCP gratuito») aparecen como opciones sin clave en su tabla de proveedores de búsqueda web (búsqueda web, 21 de septiembre de 2026), por lo que «¿necesito realmente la fundamentación de Gemini?» es una primera pregunta razonable.

Enrutamiento del chat de Gemini mediante una puerta de enlace compatible con OpenAI

La referencia de proveedores personalizados de OpenClaw indica que se deben usar entradas models.providers.<id> explícitas «solo cuando quieras anular la URL base, las cabeceras o la lista de modelos predeterminadas», y la referencia de configuración de puertas de enlace enumera once valores api: openai-completions, openai-responses, openai-chatgpt-responses, anthropic-messages, google-generative-ai, google-vertex, github-copilot, bedrock-converse-stream, ollama, pi-messages y azure-openai-responses. El esquema de configuración de v2026.9.7 acepta un duodécimo, google-interactions, añadido el 25 de septiembre de 2026. La referencia aún no lo enumera, pero la página del proveedor de Google de OpenClaw lo documenta como una alternativa opcional al transporte google-generative-ai predeterminado, utilizando la API Interactions de Gemini mediante https://generativelanguage.googleapis.com/v1beta. Los modelos Gemini de Kunavo se alcanzan a través de su superficie compatible con OpenAI en POST /v1/chat/completions (endpoint de chat), y Kunavo no publica ningún endpoint generativelanguage, v1beta ni de Interactions; por tanto, ninguno de los adaptadores de Google llega allí, y la ruta alcanzable es un id de proveedor separado, nunca un plugin google redirigido.

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

Hay cuatro detalles fundamentales. El slug lleva guiones: el id de Kunavo es gemini-3-8-flash, mientras que los de Google y OpenClaw llevan puntos, y son cadenas diferentes. contextWindow se declara porque un modelo personalizado sin metadatos de contexto vuelve a un presupuesto de 200.000 tokens, desperdiciando la mayor parte de la ventana que registra aquí el catálogo de Kunavo (1.048.576 tokens: metadatos de Kunavo, no un límite publicado por Google). input indica que admite imágenes, porque OpenClaw configura de forma predeterminada un modelo personalizado como solo de texto. Y cost se omite, por lo que la estimación local de OpenClaw se establece en cero en esta ruta: una lectura de $0 significa que faltan metadatos, no que la inferencia sea gratuita.

Lo que esta ruta renuncia está documentado, no supuesto. En api: "openai-completions" contra un host que no pertenece a OpenAI, OpenClaw fuerza compat.supportsDeveloperRole: false y omite la preparación nativa de solicitudes: no hay service_tier, ni store de Responses o Completions, ni indicaciones de caché de prompts, ni preparación del payload compatible con razonamiento (proveedores personalizados). Las funciones adicionales específicas de Gemini también quedan fuera: params.cachedContent está documentado para ejecuciones directas de Gemini, las variables de rotación de claves son funciones del plugin, y la asignación thinkingLevel / thinkingBudget de OpenClaw se describe para el proveedor google; esta página no verificó si sobrevive a una ruta de puerta de enlace.

Kunavo no ofrece ningún modelo de embeddings ni modelos de texto a voz o de voz a texto. Por tanto, los contratos de embeddings y voz del plugin google siguen usando una clave de Google, independientemente de cómo se enrute el chat.

En cuanto a las capacidades, presta atención a quién hace la afirmación. La actual página de modelos de Google ya no muestra los límites de tokens por modelo, por lo que cualquier cifra de contexto citada en otro lugar es una copia de una fuente anterior. El catálogo de Kunavo marca visión, llamadas a funciones, streaming y contexto largo en sus listados de Gemini, y marca razonamiento en todos salvo gemini-2-5-flash. Cada afirmación está limitada a quien la publicó: verifica primero las llamadas a herramientas en tu propia tarea.

Calcula el precio del modelo que realmente elegiste

Por modelo, frente al nivel estándar de Google, porque la versión de esta comparación para toda la familia no es cierta hoy:

Las tarifas de Kunavo proceden del catálogo activo y las de Google de la página de precios consultada el 21 de septiembre de 2026; la ventana inicial termina el 31 de diciembre de 2026, después de lo cual la comparación de Flash vuelve a invertirse.

Una estimación práctica, que es aritmética de tokens y no una tarea de OpenClaw medida ni un límite de facturación. Supón una semana de trabajo del asistente que envía 4.000.000 de tokens de entrada sin caché y recibe 150.000 tokens de salida, sin caché ni búsqueda. En Gemini 3.8 Flash con las tarifas de Kunavo, eso equivale a $2.49; la misma aritmética con la tarifa inicial de Flash de Google da $3.56, y aumenta a $7.13 con la tarifa de 2027. Ejecuta los mismos volúmenes en Gemini 3.6 Flash con Kunavo y obtienes $4.99, por encima de la cifra inicial de Google, que es exactamente el motivo por el que el id del modelo, no el nombre del proveedor, es la decisión.

El importe del catálogo de Kunavo es un mínimo de facturación, no un límite: cuando el servicio ascendente comunica su cargo, la factura es el mayor valor entre el coste del catálogo y el coste ascendente multiplicado por el margen aplicable. Los cargos de caché, la fundamentación de búsquedas y el alojamiento quedan fuera de este ejemplo, y la recarga mínima es de $10 en crédito prepagado: un mínimo de financiación, no una tarifa por tarea ni una suscripción. Consulta detalles de facturación y precios de OpenClaw para conocer la factura operativa completa.

Verifica con una solicitud y después lee ambos libros de cuentas

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 lee el inventario publicado y openclaw models status muestra el valor predeterminado y el estado de autenticación resueltos; ninguno demuestra que una tarea de pago funcione, y openclaw models set con un proveedor conocido guarda un modelo no catalogado mostrando solo una advertencia. openclaw doctor --json --severity-min info también muestra los modelos activos que el catálogo local no puede confirmar (referencia de CLI). La solicitud única anterior es la primera evidencia que genera un coste.

Haz el diagnóstico por código de estado. OpenClaw documenta la firma model_not_found para un servidor local compatible con OpenAI, y los tres campos que menciona son los mismos tres que configura una entrada de proveedor personalizado: verifica que baseUrl incluya /v1, que api sea "openai-completions" para un backend /v1/chat/completions, y que models[].id sea el id básico local del proveedor, usando el prefijo del proveedor solo al seleccionarlo (resolución de problemas). Contra Kunavo, la comprobación que indica que la URL base es correcta es una solicitud no autenticada a una ruta de API real: GET https://api.kunavo.com/v1/models responde 401 con un cuerpo authentication_error, lo que significa que la URL es correcta y que falta la clave. El host básico y la ruta básica /v1 no son rutas de API y responden con HTML, por lo que un cliente dirigido a cualquiera de ellos fallará antes de llegar a un modelo (comprobado el 21 de septiembre de 2026). Un 403 es el código que debes detenerte a analizar: OpenClaw advierte que «puede proceder de una capa de seguridad ascendente, como una CDN, un WAF, una regla de gestión de bots o un proxy inverso», y que un curl mínimo exitoso no garantiza que las solicitudes reales con estilo de SDK atraviesen la misma capa. Consulta model not found y la clave de API de Gemini no funciona para las versiones completas.

Para la ruta nativa, empieza por las notas de clave de API de Gemini de Kunavo y Google AI Studio; para la ruta de puerta de enlace, crea una clave en Claves de API y abre una cuenta de Kunavo, y después sigue el tutorial de proveedores personalizados en la mejor API para OpenClaw. Mantén disponible tu ruta funcional mientras haces las pruebas.

Qué ruta gana en cada caso

Si todavía estás eligiendo un proveedor y no configurándolo, precios de la API de Gemini y API compatible con OpenAI cubren las dos partes de esa decisión.

Preguntas frecuentes

Recopilado para esta página el 21 de septiembre de 2026: documentación de OpenClaw sobre el proveedor de Google, los plugins de proveedores oficiales, la búsqueda de Gemini, la búsqueda web, los proveedores personalizados (tanto los conceptos como la referencia de puertas de enlace), las reglas rápidas, los modelos de CLI y la resolución de problemas; la página de precios de la API de Gemini de Google (actualizada por última vez el 16 de septiembre de 2026), su página de modelos, su página de fundamentación mediante Google Search y su publicación del blog de desarrolladores del 19 de mayo de 2026; la entrada del registro npm para openclaw; y el catálogo propio de Kunavo. El 1 de octubre de 2026 se volvieron a comprobar los valores api de proveedores personalizados frente a la referencia de puertas de enlace, la página del proveedor de Google y el esquema de configuración de OpenClaw y el transporte Interactions en su código fuente de v2026.9.7. La única solicitud en tiempo real realizada para esta página fue una GET no autenticada a /v1/models de Kunavo, para registrar el 401 descrito anteriormente. Nada de esto se probó en tiempo de ejecución contra una instalación de OpenClaw, el endpoint de Kunavo ni Google; todas las cifras en dólares son cálculos ilustrativos basados en tarifas publicadas.