3 métodos para resolver falhas na invocação de reconhecimento de imagem do Gemini no OpenClaw: erros comuns no modo compatível com OpenAI e guia de configuração de formato nativo

O uso do modo compatível com OpenAI no OpenClaw para invocar o Modelo de Linguagem Grande Gemini em tarefas de reconhecimento de imagem é um problema comum que muitos desenvolvedores enfrentam ao configurar agentes de IA multimodais. Este artigo analisa profundamente a causa raiz do erro "Invalid JSON payload" e oferece 3 soluções comprovadas para ajudar você a corrigir rapidamente as falhas de reconhecimento de imagem do Gemini no OpenClaw.

Valor central: Ao ler este artigo, você entenderá as diferenças cruciais entre o modo compatível com OpenAI e a API nativa do Gemini, dominará o método de configuração correto e resolverá de vez as falhas no reconhecimento de imagem.

Fenômenos de erro no reconhecimento de imagem do Gemini no OpenClaw

Após configurar o modelo Gemini no OpenClaw, ao tentar realizar o reconhecimento de imagem, os logs de backend geralmente apresentam os seguintes erros típicos:

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 principais do erro de reconhecimento de imagem do Gemini no OpenClaw

Diagnóstico rápido de falhas no reconhecimento de imagem do Gemini no OpenClaw

Um equívoco comum é acreditar que a capacidade de reconhecimento de imagem do Gemini está com problemas. Na verdade, ao testar a API usando a demonstração oficial de compreensão visual do Gemini, a função de reconhecimento de imagem funciona perfeitamente. O problema reside na incompatibilidade de formato quando o OpenClaw encaminha a solicitação através do modo compatível com OpenAI.

O método de verificação é simples:

# Invocação direta da API do Gemini para testar o reconhecimento de imagem — funciona perfeitamente
import google.generativeai as genai
import PIL.Image

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

image = PIL.Image.open("test.jpg")
response = model.generate_content(["Descreva esta imagem", image])
print(response.text)  # ✅ Saída normal da descrição da imagem

🎯 Sugestão de diagnóstico: Se você encontrar problemas de reconhecimento de imagem do Gemini no OpenClaw, primeiro confirme se a chave API e o próprio modelo estão funcionando corretamente da maneira acima. Você também pode testar rapidamente a capacidade de compreensão visual do Gemini através da plataforma APIYI (apiyi.com), que lida automaticamente com problemas de compatibilidade de formato.

Análise da causa raiz da falha de reconhecimento de imagem no OpenClaw Gemini

Para escolher a solução mais adequada, precisamos entender a causa raiz do problema. A falha na invocação do reconhecimento de imagem do Gemini pelo OpenClaw ocorre, fundamentalmente, devido a um problema de compatibilidade com o JSON Schema.

Diferenças de JSON Schema entre OpenAI e Gemini na invocação de ferramentas

Quando o OpenClaw utiliza o modo de compatibilidade com a OpenAI (openai-completions) para invocar o Gemini, o fluxo da requisição ocorre da seguinte forma:

OpenClaw constrói a requisição (formato OpenAI)
    ↓
Inclui o JSON Schema da definição da ferramenta
    ↓
Envia para o endpoint compatível com OpenAI do Gemini
    ↓
Gemini analisa as function_declarations
    ↓
❌ Encontra campos de Schema não suportados → Erro 400

Lista de campos de JSON Schema não suportados pela API do Gemini

Este é o cerne do problema. O suporte do Gemini para function_declarations em JSON Schema é um subconjunto limitado, e os seguintes campos resultarão diretamente em um erro 400:

Por que trocar para o GPT-5.4 resolve o problema

Isso confirma ainda mais a nossa análise da causa raiz. Quando trocamos o modelo de Gemini para GPT-5.4 no OpenClaw, o reconhecimento de imagem volta a funcionar imediatamente, pois a API do GPT-5.4 suporta nativamente a especificação completa do JSON Schema, tornando o Schema de definição de ferramenta gerado pelo OpenClaw totalmente compatível.

📌 Conclusão importante: O problema não é a capacidade de reconhecimento de imagem do Gemini, mas sim o fato de que o Schema de ferramenta enviado pelo modo de compatibilidade OpenAI do OpenClaw não corresponde aos requisitos de formato da API do Gemini.

Solução 1: Mudar para o formato nativo do Gemini (Recomendado)

A solução mais eficaz é alterar o tipo de interface da API do Gemini no OpenClaw de openai-completions para o formato nativo google-generative-ai.

Passos de configuração

Antes da alteração (Modo compatível com OpenAI — com problemas):

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

Após a alteração (Formato nativo do Gemini — Recomendado):

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

Principais mudanças na configuração do formato nativo

Alternância rápida via CLI do OpenClaw

# Método 1: Reinicializar a configuração do Gemini
openclaw onboard --auth-choice gemini-api-key

# Método 2: Editar o arquivo de configuração manualmente
# Localização do arquivo: ~/.openclaw/config.json
# Altere o campo api de "openai-completions" para "google-generative-ai"

{
  "providers": {
    "google": {
      "apiKey": "SUA_CHAVE_API_GEMINI",
      "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
        }
      }
    }
  }
}

🚀 Início rápido: Se você não quer lidar manualmente com problemas de compatibilidade de configuração, recomendamos usar a interface unificada da plataforma APIYI (apiyi.com). A plataforma converte automaticamente as solicitações no formato OpenAI para o formato nativo do Gemini, sem que o desenvolvedor precise se preocupar com as diferenças de Schema.

Solução 2: Processamento automático de compatibilidade via serviço proxy de API

Se você deseja continuar usando o modo compatível com OpenAI no OpenClaw para invocar vários modelos (incluindo o Gemini), pode resolver os problemas de compatibilidade de formato através de um serviço proxy de API.

Como funciona o serviço proxy

OpenClaw (Solicitação em formato OpenAI)
    ↓
Serviço proxy de API (como o APIYI)
    ↓ Limpeza automática de campos JSON Schema incompatíveis
    ↓ Conversão automática do formato de solicitação
API do Gemini (Formato nativo)
    ↓
✅ Retorno normal do resultado de reconhecimento de imagem

Exemplo de configuração

# Invocação de reconhecimento de imagem do Gemini via serviço proxy APIYI
import openai
import base64

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

# Ler e codificar a imagem
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": "Descreva o conteúdo desta imagem"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{image_data}"
                    }
                }
            ]
        }
    ]
)
print(response.choices[0].message.content)

Comparação: Serviço proxy vs. Conexão direta

Configurando o proxy APIYI no OpenClaw:

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

💡 Sugestão: Se você utiliza vários modelos no OpenClaw (GPT-5.4, Claude, Gemini, etc.), gerenciar as invocações de API através do APIYI (apiyi.com) é uma escolha mais eficiente, evitando a necessidade de configurar formatos de API diferentes para cada modelo.

Solução 3: Limpeza manual de campos incompatíveis do JSON Schema

Se você precisa resolver problemas de compatibilidade no nível do código, pode limpar manualmente os campos do JSON Schema que o Gemini não suporta antes de enviar a requisição.

Função de limpeza do JSON Schema

def clean_schema_for_gemini(schema: dict) -> dict:
    """Limpa campos do JSON Schema não suportados pelo Gemini"""
    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):
    """Limpeza recursiva de campos do JSON Schema não suportados pelo Gemini"""
    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):
    """Limpa todos os Schemas na lista de ferramentas"""
    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

# Exemplo de uso
tools = [
    {
        "type": "function",
        "function": {
            "name": "analyze_image",
            "description": "Analisa o conteúdo da imagem",
            "parameters": {
                "type": "object",
                "properties": {
                    "image_url": {"type": "string"},
                    "detail": {"type": "string", "const": "high"}  # Gemini não suporta
                },
                "patternProperties": {"^x-": {"type": "string"}},  # Gemini não suporta
                "additionalProperties": False  # Gemini não suporta
            }
        }
    }
]

# Chamada após a limpeza
cleaned_tools = clean_tools_for_gemini(tools)

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

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

⚠️ Atenção: A solução de limpeza manual de Schema exige que você processe a definição de parâmetros de cada ferramenta, o que gera um custo de manutenção elevado. Se o número de ferramentas for grande ou mudar com frequência, considere priorizar a Solução 1 (formato nativo) ou a Solução 2 (serviço proxy de API).

Comparação das 3 soluções e recomendações de escolha

Árvore de decisão para seleção

• Usar apenas Gemini no OpenClaw → Solução 1 (formato nativo), mais estável
• Usar vários modelos no OpenClaw → Solução 2 (proxy APIYI), mais prático
• Precisa de controle refinado em aplicação própria → Solução 3 (limpeza manual), mais flexível
• Não sabe qual escolher → Experimente primeiro a Solução 2, validando rapidamente via APIYI (apiyi.com)

Perguntas Frequentes

Conclusão

A causa raiz da falha no reconhecimento de imagem do Gemini via OpenClaw é a incompatibilidade de campos do JSON Schema no modo compatível com OpenAI, e não uma falha na capacidade visual do modelo Gemini. As 3 soluções apresentadas possuem cenários de aplicação distintos:

• Formato nativo (google-generative-ai): A solução mais completa, recomendada para cenários que utilizam apenas o Gemini.
• Serviço proxy de API: A solução mais prática, recomendada para cenários que utilizam múltiplos modelos.
• Limpeza manual do Schema: A solução mais flexível, recomendada para sistemas desenvolvidos internamente.

Recomendamos utilizar a plataforma APIYI (apiyi.com) para validar rapidamente o desempenho do reconhecimento de imagem do Gemini. A plataforma suporta a invocação unificada dos principais modelos, como Gemini, GPT e Claude, tratando automaticamente as diferenças de formato de API entre eles.

Referências

1. Documentação oficial do Gemini – Compreensão de imagens: Explicação sobre a capacidade de compreensão visual do Gemini

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

2. Documentação oficial do Gemini – Compatibilidade com OpenAI: Instruções para invocar o Gemini via SDK da OpenAI

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

3. Issue #21172 do GitHub do OpenClaw: Erro 400 na API do Gemini causado por patternProperties

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

4. Issue #14456 do GitHub do OpenClaw: Erro 400 no modo de compatibilidade OpenAI do Gemini 2.5 Flash

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

5. Documentação de configuração de modelos do OpenClaw: Guia de configuração de provedores de modelos

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

📝 Autor deste artigo: Equipe APIYI — Focada em integração de API de Modelos de Linguagem Grande e análise técnica
🔗 Mais tutoriais: Acesse a APIYI em apiyi.com para obter mais guias de invocação do modelo e créditos de teste gratuitos