Tutorial de Integración de la API de OpenClaw Gemini

Este tutorial describe cómo configurar y utilizar los modelos de Google Gemini en OpenClaw. OpenClaw admite múltiples métodos de acceso; puedes elegir el esquema que mejor se adapte a tus necesidades.

---

Introducción

Google Gemini es un modelo de IA multimodal desarrollado por Google DeepMind, compatible con varias formas de entrada como texto, imágenes y video. Al usar Gemini en OpenClaw, puedes obtener:

• Gemini 2.0 Flash: ventana de contexto de 1 millón de tokens, ideal para escenarios de respuesta rápida y alta frecuencia.
• Gemini 1.5 Pro: ventana de contexto de 2 millones de tokens, ideal para razonamiento complejo y generación de código.
• Gemini 1.5 Flash: ventana de contexto de 1 millón de tokens, la elección equilibrada entre velocidad y eficiencia.

Método 1: Integración de Gemini mediante Defapi (Recomendado)

Defapi es una plataforma que agrega múltiples APIs de modelos de lenguaje de gran tamaño (LLM), diseñada para ofrecer a los desarrolladores servicios más económicos y estables.

Ventajas de Defapi

• Precios preferenciales: solo el 50% del precio oficial.
• Totalmente compatible: compatible con interfaces estándar como OpenAI v1/chat/completions, Anthropic v1/messages, Google v1beta/models/, etc.
• Sin cambios de código: para cambiar a Defapi solo necesitas modificar la baseUrl; el código original no requiere ninguna modificación.
• Soporte multimodelo: accede a Gemini, Claude, GPT y otros modelos desde una sola plataforma.

Método de Integración

Opción A: Llamada directa a Defapi

# Establecer variable de entorno
export DEFAPI_API_KEY="tu_clave_Defapi"

# Configurar OpenClaw para usar Defapi
{
  env: { DEFAPI_API_KEY: "dk-..." },
  agents: {
    defaults: {
      model: { primary: "defapi/gemini-3-flash" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      "defapi": {
        baseUrl: "https://api.defapi.org/v1beta",
        apiKey: "${DEFAPI_API_KEY}",
        api: "google-generative-ai",
        models: [
          {
            id: "gemini-3-flash",
            name: "Gemini 3 Flash",
            contextWindow: 1000000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

Opción B: A través de la interfaz compatible con OpenAI

si tu aplicación utiliza el formato de OpenAI:

{
  models: {
    mode: "merge",
    providers: {
      "defapi-openai": {
        baseUrl: "https://api.defapi.org/v1/chat/completions",
        apiKey: "${DEFAPI_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "gemini-3-flash", name: "Gemini 3 Flash", contextWindow: 1000000 },
        ],
      },
    },
  },
}

Modelos Gemini compatibles con Defapi

Obtener Defapi

Visita el sitio oficial de Defapi para registrar una cuenta, obtener tu API Key y comenzar a usarlo.

---

Método 2: Uso directo de la API oficial de Google

Obtener la API Key

1. Visita Google AI Studio
2. Inicia sesión con tu cuenta de Google
3. Haz clic en "Get API Key" para crear una nueva clave
4. Copia la clave para su uso posterior

Configuración de la CLI

# Configuración interactiva
openclaw onboard --auth-choice google-api-key

# Configuración no interactiva (variables de entorno)
export GOOGLE_API_KEY="tu_clave_API"
openclaw onboard --google-api-key "$GOOGLE_API_KEY"

Archivo de configuración

Ruta del archivo: ~/.openclaw/openclaw.json

{
  env: { GOOGLE_API_KEY: "AIza..." },
  agents: { defaults: { model: { primary: "google-generative-ai/gemini-1.5-flash" } } },
}

Modelos compatibles

---

Método 3: Integración unificada con OpenRouter

OpenRouter proporciona un endpoint de API unificado que permite acceder simultáneamente a modelos de múltiples proveedores.

Obtener la API Key de OpenRouter

1. Visita OpenRouter para registrar una cuenta
2. Obtén la API Key en la consola

Configuración de la CLI

export OPENROUTER_API_KEY="sk-or-..."
openclaw onboard --auth-choice apiKey --token-provider openrouter --token "$OPENROUTER_API_KEY"

Archivo de configuración

Ruta del archivo: ~/.openclaw/openclaw.json

{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      model: { primary: "openrouter/google/gemini-2.0-flash-exp" },
    },
  },
}

💡 Ventajas de OpenRouter

• Comparación de precios de múltiples proveedores: puedes elegir modelos Gemini de diferentes proveedores
• Interfaz unificada: solo necesitas una API Key para acceder a múltiples modelos
• Compatible con el formato de OpenAI: cambia de modelo sin modificar el código

---

Método 4: Integración de proveedor personalizado

Si la plataforma ofrece una interfaz /v1/chat/completions compatible con OpenAI, se puede configurar como un proveedor personalizado.

Ejemplo de archivo de configuración

Ruta del archivo: ~/.openclaw/openclaw.json

{
  agents: {
    defaults: {
      model: { primary: "custom-gemini/gemini-1.5-flash" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      "custom-gemini": {
        baseUrl: "https://your-gemini-proxy.example.com/v1",
        apiKey: "${CUSTOM_GEMINI_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "gemini-1.5-flash",
            name: "Gemini 1.5 Flash",
            contextWindow: 1000000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

Descripción de los campos de configuración

---

Configuración de Thinking Blocks

Los modelos Gemini 2.0 admiten Thinking Blocks para ampliar la capacidad de razonamiento. OpenClaw gestiona automáticamente estas configuraciones para asegurar la compatibilidad:

Ruta del archivo: ~/.openclaw/openclaw.json

{
  agents: {
    defaults: {
      models: {
        "google-generative-ai/gemini-2.0-flash-exp": {
          params: {
            thinkingConfig: {
              thinkingBudget: 8192,
            },
          },
        },
      },
    },
  },
}

---

Resolución de problemas comunes

Error 401 / API Key inválida

• Verifica que la API Key sea correcta y no haya sido revocada.
• Comprueba si la Key tiene permisos para acceder a la Generative Language API.

Límites de velocidad (Rate Limit)

• Gemini tiene límites de velocidad basados en niveles (Nivel gratuito: 15 RPM).
• Monitorea el uso en el panel de control de Google AI Studio.
• Solución: Usa Defapi para obtener límites de llamada más altos.

Error de Schema de herramientas

• Google no admite ciertas palabras clave de JSON Schema (como patternProperties, additionalProperties, etc.).
• OpenClaw elimina automáticamente las palabras clave no compatibles.
• Para Schemas complejos, considera dividirlos en definiciones de herramientas más simples.

Se requiere ID de proyecto

• Configura las variables de entorno GOOGLE_CLOUD_PROJECT o GOOGLE_CLOUD_PROJECT_ID.

---

Comparación de costos

Para escenarios de llamadas de alta frecuencia, el uso de Defapi puede reducir significativamente los costos.