3 formas de resolver el fallo de reconocimiento de imágenes de Gemini en OpenClaw: errores comunes en el modo compatible con OpenAI y guía de configuración de formato nativo

El uso del modo compatible con OpenAI en OpenClaw para invocar modelos Gemini y realizar reconocimiento de imágenes suele generar errores, lo cual es un punto de dolor común para muchos desarrolladores al configurar agentes de IA multimodales. En este artículo, analizaremos a fondo la causa raíz del error "Invalid JSON payload" y te ofreceremos 3 soluciones probadas para que puedas reparar rápidamente los fallos de reconocimiento de imágenes con Gemini en OpenClaw.

Valor central: Al terminar de leer, entenderás las diferencias clave entre el modo compatible con OpenAI y la API nativa de Gemini, dominarás el método de configuración correcto y resolverás definitivamente los fallos en el reconocimiento de imágenes.

Fenómeno de error en el reconocimiento de imágenes con Gemini en OpenClaw

Tras configurar el modelo Gemini en OpenClaw, al intentar realizar un reconocimiento de imágenes, los registros del sistema suelen mostrar el siguiente error típico:

Invalid JSON payload received. Unknown name "patternProperties"
at 'tools[0].function_declarations[3].parameters.properties[4].value':
Cannot find field.

Invalid JSON payload received. Unknown name "const"
at 'tools[0].function_declarations[37].parameters.properties[0].value':
Cannot find field.

Características clave del error de reconocimiento de imágenes con Gemini en OpenClaw

Diagnóstico rápido del fallo de reconocimiento de imágenes con Gemini en OpenClaw

Un error común es pensar que la capacidad de reconocimiento de imágenes de Gemini tiene problemas. En realidad, si pruebas la API directamente con la demo oficial de comprensión visual de Gemini, la función de reconocimiento de imágenes funciona perfectamente. El problema reside en la incompatibilidad de formato cuando OpenClaw redirige la solicitud a través del modo compatible con OpenAI.

El método de verificación es sencillo:

# Invocación directa de la API de Gemini para probar el reconocimiento de imágenes — Funciona perfectamente
import google.generativeai as genai
import PIL.Image

genai.configure(api_key="TU_CLAVE_API_GEMINI")
model = genai.GenerativeModel("gemini-2.5-flash")

image = PIL.Image.open("test.jpg")
response = model.generate_content(["Describe esta imagen", image])
print(response.text)  # ✅ Salida normal de la descripción de la imagen

🎯 Sugerencia de diagnóstico: Si encuentras problemas con el reconocimiento de imágenes de Gemini en OpenClaw, primero verifica de la forma anterior que tu clave API y el modelo funcionen correctamente. También puedes probar rápidamente la capacidad de comprensión visual de Gemini a través de la plataforma APIYI (apiyi.com), la cual gestiona automáticamente los problemas de compatibilidad de formato.

Análisis de la causa raíz del fallo en el reconocimiento de imágenes de Gemini en OpenClaw

Entender la causa raíz de un problema es fundamental para elegir la solución más adecuada. El fallo de OpenClaw al realizar el reconocimiento de imágenes con Gemini tiene una causa central: un problema de compatibilidad con el esquema JSON (JSON Schema).

Diferencias en el esquema JSON para llamadas a herramientas entre OpenAI y Gemini

Cuando OpenClaw utiliza el modo de compatibilidad con OpenAI (openai-completions) para invocar a Gemini, el flujo de la solicitud es el siguiente:

OpenClaw construye la solicitud (formato OpenAI)
    ↓
Incluye el esquema JSON con la definición de la herramienta
    ↓
Envío al endpoint compatible con OpenAI de Gemini
    ↓
Gemini analiza las function_declarations
    ↓
❌ Encuentra campos de esquema no compatibles → Error 400

Lista de campos de JSON Schema no compatibles con la API de Gemini

Este es el núcleo del problema. El soporte de Gemini para function_declarations en el esquema JSON es un subconjunto limitado; los siguientes campos provocarán directamente un error 400:

¿Por qué al cambiar a GPT-5.4 funciona sin problemas?

Esto confirma aún más el análisis de la causa raíz. Cuando se cambia el modelo de Gemini a GPT-5.4 en OpenClaw, el reconocimiento de imágenes vuelve a la normalidad inmediatamente, ya que la API de GPT-5.4 admite de forma nativa la especificación completa de JSON Schema, por lo que el esquema de definición de herramientas generado por OpenClaw es totalmente compatible.

📌 Conclusión clave: No es un problema de la capacidad de reconocimiento de imágenes de Gemini, sino que el esquema de herramientas enviado por el modo de compatibilidad con OpenAI de OpenClaw no coincide con los requisitos de formato de la API de Gemini.

Solución 1: Cambiar al formato nativo de Gemini (Recomendado)

La solución más definitiva en OpenClaw es cambiar el tipo de interfaz API de Gemini de openai-completions al formato nativo google-generative-ai.

Pasos de configuración

Antes de la modificación (Modo compatible con OpenAI — presenta problemas):

{
  "provider": "google",
  "model": "gemini-2.5-flash",
  "baseUrl": "https://generativelanguage.googleapis.com/v1beta/openai",
  "api": "openai-completions",
  "apiKey": "YOUR_GEMINI_API_KEY"
}

Después de la modificación (Formato nativo de Gemini — recomendado):

{
  "provider": "google",
  "model": "gemini-2.5-flash",
  "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
  "api": "google-generative-ai",
  "apiKey": "YOUR_GEMINI_API_KEY"
}

Cambios clave en la configuración del formato nativo

Cambio rápido mediante la CLI de OpenClaw

# Método 1: Reinicializar la configuración de Gemini
openclaw onboard --auth-choice gemini-api-key

# Método 2: Editar manualmente el archivo de configuración
# Ubicación del archivo: ~/.openclaw/config.json
# Cambiar el campo api de "openai-completions" a "google-generative-ai"

{
  "providers": {
    "google": {
      "apiKey": "YOUR_GEMINI_API_KEY",
      "models": {
        "gemini-2.5-flash": {
          "api": "google-generative-ai",
          "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
          "capabilities": {
            "vision": true,
            "functionCalling": true,
            "streaming": true
          },
          "reasoning": false
        },
        "gemini-2.5-pro": {
          "api": "google-generative-ai",
          "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
          "capabilities": {
            "vision": true,
            "functionCalling": true,
            "streaming": true
          },
          "reasoning": true,
          "thinkingBudget": 8192
        }
      }
    }
  }
}

🚀 Inicio rápido: Si no deseas gestionar manualmente los problemas de compatibilidad de configuración, te recomendamos utilizar la interfaz unificada de la plataforma APIYI (apiyi.com). La plataforma convierte automáticamente las solicitudes en formato OpenAI al formato nativo de Gemini, por lo que los desarrolladores no tienen que preocuparse por las diferencias de esquema.

Solución 2: Gestionar la compatibilidad mediante un servicio proxy de API

Si deseas seguir utilizando el modo compatible con OpenAI en OpenClaw para invocar varios modelos (incluido Gemini), puedes resolver los problemas de compatibilidad de formato a través de un servicio proxy de API.

Cómo funciona el servicio proxy

OpenClaw (Solicitud en formato OpenAI)
    ↓
Servicio proxy de API (ej. APIYI)
    ↓ Limpieza automática de campos JSON Schema incompatibles
    ↓ Conversión automática del formato de solicitud
Gemini API (Formato nativo)
    ↓
✅ Resultado de reconocimiento de imagen devuelto correctamente

Ejemplo de configuración

# Invocar el reconocimiento de imagen de Gemini a través del servicio proxy de APIYI
import openai
import base64

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # Interfaz unificada de APIYI
)

# Leer y codificar la imagen
with open("test.jpg", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

response = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Describe el contenido de esta imagen"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{image_data}"
                    }
                }
            ]
        }
    ]
)
print(response.choices[0].message.content)

Comparativa: Conexión directa vs. Servicio proxy de APIYI

Configuración del proxy de APIYI en OpenClaw:

{
  "provider": "apiyi",
  "model": "gemini-2.5-flash",
  "baseUrl": "https://api.apiyi.com/v1",
  "api": "openai-completions",
  "apiKey": "YOUR_APIYI_KEY"
}

💡 Sugerencia: Si utilizas varios modelos en OpenClaw (GPT-5.4, Claude, Gemini, etc.), gestionar las invocaciones de API de forma unificada a través de APIYI (apiyi.com) es una opción mucho más eficiente, ya que evita tener que configurar formatos de API distintos para cada modelo.

Solución 3: Limpieza manual de campos incompatibles en el JSON Schema

Si necesitas resolver los problemas de compatibilidad a nivel de código, puedes limpiar manualmente los campos del JSON Schema que Gemini no admite antes de enviar la solicitud.

Función de limpieza de JSON Schema

def clean_schema_for_gemini(schema: dict) -> dict:
    """Limpia los campos del JSON Schema que Gemini no admite"""
    unsupported_keys = {
        "patternProperties",
        "const",
        "additionalProperties",
        "$schema",
        "exclusiveMaximum",
        "exclusiveMinimum",
        "propertyNames",
    }

    if isinstance(schema, dict):
        return {
            k: clean_schema_for_gemini(v)
            for k, v in schema.items()
            if k not in unsupported_keys
        }
    elif isinstance(schema, list):
        return [clean_schema_for_gemini(item) for item in schema]
    return schema

import openai
import json

def clean_schema_for_gemini(schema):
    """Limpia recursivamente los campos del JSON Schema que Gemini no admite"""
    unsupported_keys = {
        "patternProperties", "const", "additionalProperties",
        "$schema", "exclusiveMaximum", "exclusiveMinimum",
        "propertyNames", "if", "then", "else",
        "allOf", "anyOf", "oneOf", "not",
    }

    if isinstance(schema, dict):
        cleaned = {}
        for k, v in schema.items():
            if k not in unsupported_keys:
                cleaned[k] = clean_schema_for_gemini(v)
        return cleaned
    elif isinstance(schema, list):
        return [clean_schema_for_gemini(item) for item in schema]
    return schema

def clean_tools_for_gemini(tools):
    """Limpia todos los esquemas en la lista de herramientas"""
    cleaned_tools = []
    for tool in tools:
        tool_copy = json.loads(json.dumps(tool))
        if "function" in tool_copy:
            params = tool_copy["function"].get("parameters", {})
            tool_copy["function"]["parameters"] = clean_schema_for_gemini(params)
        cleaned_tools.append(tool_copy)
    return cleaned_tools

# Ejemplo de uso
tools = [
    {
        "type": "function",
        "function": {
            "name": "analyze_image",
            "description": "Analiza el contenido de la imagen",
            "parameters": {
                "type": "object",
                "properties": {
                    "image_url": {"type": "string"},
                    "detail": {"type": "string", "const": "high"}  # No compatible con Gemini
                },
                "patternProperties": {"^x-": {"type": "string"}},  # No compatible con Gemini
                "additionalProperties": False  # No compatible con Gemini
            }
        }
    }
]

# Llamada tras la limpieza
cleaned_tools = clean_tools_for_gemini(tools)

client = openai.OpenAI(
    api_key="TU_CLAVE_API",
    base_url="https://api.apiyi.com/v1"
)

response = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[{"role": "user", "content": "Hola"}],
    tools=cleaned_tools
)

⚠️ Nota: La solución de limpieza manual requiere que proceses la definición de parámetros de cada herramienta, lo que conlleva un alto coste de mantenimiento. Si tienes muchas herramientas o cambian con frecuencia, te recomiendo priorizar la Solución 1 (formato nativo) o la Solución 2 (servicio proxy de API).

Comparativa de las 3 soluciones y recomendaciones de selección

Árbol de decisión para la selección

• Solo usar Gemini en OpenClaw → Solución 1 (formato nativo), la más estable.
• Uso mixto de varios modelos en OpenClaw → Solución 2 (proxy de APIYI), la más cómoda.
• Aplicaciones de IA propias que requieren control preciso → Solución 3 (limpieza manual), la más flexible.
• No estás seguro de cuál elegir → Prueba primero la Solución 2, verifica rápidamente a través de APIYI (apiyi.com).

Preguntas frecuentes

Resumen

La causa fundamental del fallo en el reconocimiento de imágenes de Gemini mediante OpenClaw es la incompatibilidad de los campos de JSON Schema en el modo compatible con OpenAI, y no un problema con las capacidades visuales del Modelo de Lenguaje Grande de Gemini. Las 3 soluciones propuestas tienen sus propios escenarios de uso:

• Formato nativo (google-generative-ai): La más completa, recomendada para escenarios donde solo se utiliza Gemini.
• Servicio proxy de API: La más sencilla, recomendada para escenarios donde se mezclan varios modelos.
• Limpieza manual del esquema: La más flexible, recomendada para sistemas construidos a medida.

Se recomienda utilizar APIYI (apiyi.com) para verificar rápidamente el rendimiento del reconocimiento de imágenes de Gemini. La plataforma admite la invocación unificada de modelos principales como Gemini, GPT y Claude, gestionando automáticamente las diferencias de formato entre las APIs de cada modelo.

Referencias

1. Documentación oficial de Gemini – Comprensión de imágenes: Explicación de las capacidades de comprensión visual de Gemini

   • Enlace: ai.google.dev/gemini-api/docs/image-understanding

2. Documentación oficial de Gemini – Compatibilidad con OpenAI: Instrucciones para la invocación del modelo Gemini mediante el SDK de OpenAI

   • Enlace: ai.google.dev/gemini-api/docs/openai

3. Issue #21172 de OpenClaw en GitHub: Error 400 en la API de Gemini causado por patternProperties

   • Enlace: github.com/openclaw/openclaw/issues/21172

4. Issue #14456 de OpenClaw en GitHub: Error 400 en el modo de compatibilidad con OpenAI de Gemini 2.5 Flash

   • Enlace: github.com/openclaw/openclaw/issues/14456

5. Documentación de configuración de modelos de OpenClaw: Guía de configuración para proveedores de modelos

   • Enlace: docs.openclaw.ai/concepts/model-providers

📝 Autor del artículo: Equipo de APIYI — Especialistas en integración de API de Modelos de Lenguaje Grande y análisis técnico
🔗 Más tutoriales: Visita APIYI en apiyi.com para obtener más guías de invocación del modelo y créditos de prueba gratuitos